AS/400 Advanced Series 


Application Display Programming 


Version 4 


SC41-5715-00 


TTT | 


AS/400 Advanced Series 


Application Display Programming 


Version 4 


SC41-5715-00 


TTT | 


-—— Take Note! 


Before using this information and the product it supports, be sure to read the general information under “Notices” on page xxix. 


First Edition (August 1997) 


This edition applies to the licensed program IBM Operating System/400 (Program 5769-SS1), Version 4 Release 1 Modification 0, 
and to all subsequent releases and modifications until otherwise indicated in new editions. 


Make sure that you are using the proper edition for the level of the product. 


Order publications through your IBM representative or the IBM branch serving your locality. If you live in the United States, Puerto 
Rico, or Guam, you can order publications through the IBM Software Manufacturing Solutions at 800+879-2755. Publications are not 
stocked at the address given below. 


IBM welcomes your comments. A form for readers’ comments may be provided at the back of this publication. You can also mail 
your comments to the following address: 


IBM Corporation 

Attention Department 542 
IDCLERK 

3605 Highway 52 N 

Rochester, MN 55901-7829 USA 


or you can fax your comments to: 


United States and Canada: 800+937-3430 
Other countries: (+1)+507+253-5192 


If you have access to Internet, you can send your comments electronically to IDCLERK@RCHVMW2.VNET.IBM.COM; IBMMAIL, to 
IBMMAIL(USIB56RZ). 


When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes 
appropriate without incurring any obligation to you. 


© Copyright International Business Machines Corporation 1997. All rights reserved. 
Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to 
restrictions set forth in GSA ADP Schedule Contract with IBM Corp. 


Contents 


NotiCeS: 6 2.202.¢ 6% 2X obo 6 A. BRAS Sis PEPER e ee he XXix 
Programming Interface Information .................0 0000004 XXX 
WTAGEMALKS: 6° sie Ae et APS ek heh ana e BPA eR Laden ae PAS XXX 
About Application Display Programming (SC41-5715)  ........... XXXI 
Who Should Use This Book ............. 0.0.00 cee eee XXxxi 
Prerequisite and Related Information ....................... XXXi 
Information Available on the World Wide Web .................. XXXI 
Summary of Changes to Application Display Programming ........ XXxiii 


Part 1. Building a Sample Display with Online Help Information 


Chapter 1. Building a Sample Display with Online Help Information ... 1-1 


Part 2. Programming Application Displays Using Display Files 


Chapter 2. Defining Your Display ina Display File .............. 2-1 
Establishing a Display File ............. 2000000000 2-1 
Determining File Descriptions ................ 000002200. 2-2 
Deciding Whether to Describe Data Inside or Outside Your Program .... 2-3 
Creating a Display File and Description ....................4. 2-4 
Changing the File Description .............. 0.20000 000004 2-5 
Detecting File Description Changes ..................22.004. 2-6 
Defining Display Fields and Functions ina Record Format ............ 2-7 
Understanding the Field Attribute Characters .................. 2-8 
Understanding How Record Format Fields Can Be Used ........... 2-9 
Defining Function Keys ........... 00000 eee ee 2-11 
Defining Command Attention (CAnn) and Command Function (CFnn) Keys 2-12 
Specifying Alternative Keys ...............20 2000500004 2-13 
Passing Information via Indicators ....................0.2. 2-14 
Inserting Constant Field Text from a Message Description ......... 2-16 
Allowing for Right-to-Left Cursor Movement .................. 2-16 
Defining Cursor Movement to Input-Capable Positions Only ........ 2-16 
Defining Cursor Progression for Entry Fields ................. 2-17 
Defining Attributes for Entry Fields ....................... 2-18 
Protecting Entry Fields Using Edit Masks ................... 2-19 
Specifying Right-to-Left Display Processing .................. 2-19 
Specifying Word Wrap for Fields ................... 20004 2-20 
Emphasizing Fields ......... 0.0000 0 ee ee ee 2-21 
Adding'Golor +, 2:.4°24 2% 2454. Wea PASS Rh we Beeler bd bas 2-22 
Editing Output Fields ............0. 0.0.00 00002 eee ee 2-23 
Defining Your Own Edit Codes ................ 0.220000. 2-23 
Specifying Valid Screen Sizes... 1... 0.0.0.0... 0000000 2 eee 2-24 
Enabling Your Display to Be Printed ...................... 2-25 
Defining Windows ........... 0200000 0 2-27 
Using Program-Described Data ...................2000004. 2-27 
Defining Input-Only Files .............. 0.002200 20 0008. 2-28 
Defining Output-Only Files ............. 2.2.2.0. 002000000. 2-28 


© Copyright IBM Corp. 1997 iii 


Defining Input and Output Files ....................0004. 


Chapter 3. Working with Display Files in an Application .......... 
Understanding How the System Allocates Resources ............... 
Opening Display Files ..............2 00.0000 00 e eee 
Acquiring a Display Station for /O Operations ................... 
Obtaining Information about Display Files and Display Stations ......... 
Obtaining Information about Open and I/O Operations ............. 
Obtaining Attribute Information about Display Stations ............. 
Sending and Receiving Data .............2....20 0200220005 
Determining Which Record Formats Are Active ona Display ......... 
Writing Output to the Display ......................200-. 
Inviting Input to the Display .................. 0.220004. 
Reading Invited Input from the Display ..................... 
Reading Input from the Display ....................2.00.. 
Writing Output and Reading Input atthe Same Time ............ 
Canceling Input That Was Not Waited For ................... 
Locking the Keyboard and Positioning the Cursor During I/O Operations 
Saving Previously Displayed Information .................... 
Understanding the Effects of I/O Operations on Command Keys ...... 
Avoiding Record Format Problems on the 5250 Display Station ...... 
Releasing an Acquired Display Station from I/O Operations .......... 
Closing Display Files ................ 0.200.000 2002000: 
Mapping Display Operations to High-Level Language Operations ....... 
Sharing Display Files inthe Same Job... . 1... 2. ee ee 
Understanding the Open Operation for Files Shared inaJob ........ 
Understanding the Input/Output Operation for Files Shared in a Job 
Understanding the Close Operation for Files Shared inaJob ....... 


Chapter 4. Displaying Groups of Records Using Subfiles .......... 
Recognizing Subfile Uses ................0 2020020000022 
Describing Subfiles in YourDDS Source ....................4. 
Using a Subfile ina Program ............... 2.202.000.5000 004 
Requesting I/O Operations fora Subfille ...................0.0. 
Requesting I/O Operations for a Subfile Record Format ........... 
Requesting I/O Operations for a Subfile Control Record Format ...... 
Recognizing Subfile I/O Requests in High-Level Languages ........ 
Controlling the Appearance of Subfiles ...................... 
Displaying Horizontal Subfiles with Display Modes  ............... 
Specifying Subfile Size Equal to Page Size .................0... 
Specifying Subfile Size Not Equal to Page Size ............2..... 
Checking Validity on Subfile Data ...................2.00.0.. 
Displaying Error Messages from Subfiles ....................0. 
Positioning the Cursor on the Displayed Subfile ................. 
Positioning the Cursor Initially ............2.......-2..20.. 
Positioning the Cursor When a Roll Key Is Used ............... 
Positioning the Cursor When a Fold or Truncate Key Is Used ....... 
Positioning the Cursor and Rolling When Two or More Records Are 
Displayed: «3. og pee de RR Ree er aba eb ae 
Understanding Subfile DDS and Program Logic-Example ........... 


Chapter 5. Defining Windows with Display Files ............... 
Window Terminology ......... 0.00. 
DDS Window Keywords .............0 000000 eee ee 


iv Application Display Programming V4R1 


Window Representation and Hardware Configuration ............... 5-3 


Creating Windows ...........0 0.0002 e ee 5-3 
Window Definition Records ............ 0.0002 eee eee 5-3 
Window Reference Records ............ 0.0000 eee eee 5-3 
Window Size and Location .................20 0000020005 5-4 
Cursor Position ..........0 0.0000 ce 5-5 
Error. Messages: oi.5 4 la ae hee al ee ee ay Ga A 5-6 
SUBTICS:, tir Seek Ue tt cae tet) MELO Sd ce kN Ne ee ae ty dhe oat ke Ae 5-6 
DDS-Help:Records:. = co seseewts ect ckendSete then is Ge So ae eer ep htc ate ad 5-7 

Defining Window Borders ..............0 000002 eee ee 5-7 
Border:DefaultS:. 20s acne wa pee eR EE Ee WU eee PE eS 5-7 
Multiple Border Definitions ............. 0... 20000022 ee, 5-8 
UIM Help Window Borders ............. 0.00000 eee eee 5-9 

Defining a Window Title .........0... 2.200000. 5-9 

Reading Data from Windows .............. 0000 eee eee 5-10 

Changing Window Borders and Contents ..................... 5-10 

Moving and Duplicating Windows ..................220000. 5-11 

Making Two Windows Seem Active atOnce ................... 5-11 

Making One Window in a Series Stand Out ................0... 5-12 

Removing Windows ........... 0000 ee 5-12 
Removing All Windows ............0 0.000 ee ee 5-13 
Removing More Recent Windows .................-.20000. 5-13 

Improving Application Performance ................ 000000 5-13 
System Save and Restore Operations ....................-. 5-13 
Bypassing System Save and Restore Operations .............. 5-14 

Programming Examples ..........0 0.00000 ee 5-15 
Using Basic Window Functions .....................004. 5-16 
Defining Windows in a Separate Display File ................. 5-20 
RPG Program Source ..... 2.2... 2.0200 eee 5-21 
RPG Program Source for WINPGM ....................-.. 5-22 

Chapter 6. Creating a Graphical Look for Displays .............. 6-1 

Factors Affecting the GraphicalLook ........................ 6-1 
Hardware Configuration .............. 0.000200 eee 6-1 
Enhanced Display Parameter ............. 2.200000 eee 6-4 

DDS Keywords ........ 2.000 0c ee 6-5 

Creating Menu Bars .......... 0.000202 6-7 
Defining the Menu-Bar Choices ...............-..200 20005 6-7 
Suppressing the Menu-Bar Separator ...................-.. 6-8 
Defining the Menu-Bar Separator ..............-..-...00.. 6-8 

Selection Fields—Overview ............. 2.000000 2c 6-10 
DDS for Selection Fields—Example ...................... 6-12 
Creating a Vertical Single-Choice Selection Field ............... 6-13 
Creating a Vertical Multiple-Choice Selection Field .............. 6-14 
Creating a Horizontal Selection Field ....................0.0. 6-14 
Cursor Movement in a Vertical Selection Field ................ 6-15 
Cursor Movement in a Horizontal Selection Field ............... 6-16 
Controlling the Selection Indicators in a Selection Field ........... 6-17 

Creating Pull-Down Menus Using Single-Choice Selection Fields ....... 6-18 
Controlling the Selection Indicators ina Pull-Down Menu .......... 6-20 
Defining Accelerator Keys ........... 0.0000 eee eee eee 6-21 
Defining a Menu-Bar Switch Key .................22.2204. 6-22 
Defining a Cancel Key ............ 2.200000 epee 6-23 
Limiting Function When Cursor is Outside a Pull-Down Menu ....... . 6-24 


Contents V 


Selection Lists—Overview ..........0.00.000000 0020000000004 6-24 


DDS for Selection Lists—Example ....................0.. 6-26 
Creating Selection Lists .......... 0.00000 00 eee eee 6-26 
Controlling the Selection Indicators in a Selection List ............ 6-28 
Scroll Bars—Overview ..........0.0 0.00000 e ee 6-30 
CreatingaScrollBar ........2...0..0 0200000000022 e ee 6-31 
DDS for Scroll Bars—Example ..................-2..2204. 6-33 
Scroll Bar Operation ........2.. 0200200000 pees 6-33 
Push Buttons—Overview ............ 0.20000 eee eee 6-34 
DDS for Push Buttons—Example .................-2...04. 6-35 
Creating Push Buttons ...........2...0-. 0.002000 0500004 6-35 
Controlling the Availability of Choices ...................0... 6-36 
Auto-Selection in Single-Choice Selection Fields ................ 6-37 
Auto-Enter in Single-Choice Selection Fields ................... 6-38 
Defining Mnemonics ........... 0.000 ee 6-38 
Defining Choice Colors and Attributes ......................-. 6-39 
Continued-Entry Fields—Overview ..............00 0.00000 eae 6-42 
Specifying Word Wrap on Continued-Entry Fields .............. 6-43 
DBCS Considerations with Continued-Entry Fields .............. 6-43 
How DBCS Data is Returned for Continued-Entry Fields .......... 6-44 
Keyboard Functions with Continued-Entry Fields ............... 6-44 
Forward Field-Exit Processing ............. 2.000002 eae 6-49 
Backward Field-Exit Processing .............-..000 055200 6-49 
How the Menu Bar Interacts with the Application ................ 6-50 
Defining the MNUBARDSP Keyword on the Application Record ...... 6-50 
Defining the MNUBARDSP Keyword on the Menu-Bar Record ....... 6-51 
Receiving Input from the Pull-Down Menus .................. 6-53 
Removing a Pull-Down Menu after Receiving Input ............. 6-55 
Updating a Pull-Down Menu before Displaying ................ 6-55 
Defining Application Help .. 2... 20.0.0... 0000 ee 6-56 
Defining Choice-Level Help .................20 0.200204. 6-56 
Defining Help fora Field ............ 0... 20000 eee 6-59 
Key Interaction for Menu Bars and Pull-Down Menus .............. 6-60 
Cursor Movement .........-.. 020000 pe ee 6-61 
Pressing the Tab Key ............ 00000 eee ee 6-61 
Pressing the Cursor Keys .............0 000002 eee eee 6-62 
Programming Examples .......... 0.000000 eee ee 6-62 
Using the MNUBARDSP Keyword on the Application Record ........ 6-62 
Using the MNUBARDSP Keyword on the Menu-Bar Record ........ 6-65 
How the Displays Look ............. 000000 eee eee 6-67 
Simple. Hotspots: 22 inedtekse eer ged oe pe Fe ee eae ee ees 6-68 
Command Key Emulation ..................2.22..200004 6-68 
Page Up and Page Down Key Emulation ................... 6-69 
Programmable Mouse Buttons—Overview .................--. 6-69 
Pointer Device Events ........0.0.0 20 ee 6-69 
AID Codes to be Returned .................20. 020000005 6-70 
Programmable Mouse Buttons—Benefits ................... 6-70 
Programmable Mouse Buttons Operation ................... 6-71 
Programmable Mouse Buttons—NWS Considerations ............ 6-72 
Programmable Mouse Buttons—Event Processing States .......... 6-72 
Programmable Mouse Buttons—Event Processing Priority ......... 6-73 
Grid Line Structures—Overview ...............20 020000005 6-79 
DDS for Grid Line Structures—Example .................... 6-80 
Grid Line Structures and Windows .....................-. 6-81 


Application Display Programming V4R1 


Hardware Requirements for Grid Line Structures ............... 6-82 


Inserting HTML Tags ..... 2... 20.0000 2 ee 6-82 
Resolving HTML Field Overlap ...............-...2..02004. 6-83 
Programming Examples .......... 0.000000 eee ee 6-85 
Chapter 7. Overriding Display Files and Display File Attributes ...... 7-1 
Determining Whether or Not to Use Overrides ................... 7-1 
Overriding File Attributes in HLL Programs ................-..-. 7-1 
Overriding File Names in HLL Programs .................-..-. 7-3 
Overriding Both File Names and Attributes in HLL Programs .......... 7-3 
Applying Overrides When Compiling a Program .................. 7-4 
Deleting Overrides ......... 00.0000. 7-5 
Displaying Overrides ..........0.2..0 02000002 7-6 
Using File Redirection to Override File Names and Libraries or File Types .. 7-6 
Overriding Files with the Same File Types .................... 7-6 
Overriding Files with Different File Types .................... 7-6 
Recognizing Commands That Ignore or Restrict Overrides ............ 7-9 
Chapter 8. Handling Messages and Errors for Display Files ........ 8-1 
Creating and Displaying YourOwn Messages ................... 8-1 
Displaying a Message on the Message Line .................. 8-2 
Displaying a Message on the Message Line When a Subfile Control Record 
ISPVVITUCM: sw astiouy Ao. Renee te A AL Mth AND oe Stes hn Rd lett i AO MN 8-2 
Displaying a Message on the Message Line Using a Message Field .... 8-3 
Priorities for Displaying Messages ona Message Line ............ 8-3 
Displaying Messages in a Field onthe Display ................. 8-3 
Displaying Messages on a Program Message Queue ............. 8-4 
Displaying Error Messages through a Subfile .................. 8-4 
Sounding an Alarm for Messages ............-..-00522 005. 8-7 
Automatically Handling Permanent I/O Errors on Display Stations ...... 8-7 
Analyzing Error Messages Sent from the System ................. 8-8 
Understanding Messages and Message Monitors ............... 8-9 
Understanding Major/Minor Return Codes ................... 8-10 
Recovering from Errors... 1.0... 2. 8-11 
Chapter 9. Creating and Accessing Menus Using Display Files ...... 9-1 
Running System and User-Defined Menus ..................... 9-1 
Returning to a Menu after Running the GO command ............. 9-1 
Determining the Previous Menu ............. 2.00000 eee 9-1 
Using the Cancel and Exit Keys on Menus ................... 9-2 
Choosing the Menu That Is Shown at Sign-On Time .............. 9-3 
Defining Your Own Display File Menus ....................... 9-4 
Understanding DDS and Display File Considerations for Menus ....... 9-4 
Describing Menu Actions ina Message File ................... 9-5 
Naming Help Formats for Menus ...............0 0.002004. 9-6 
Building a Display File Menu . 1... 9-7 
Defining YourOwn Program Menus ..................-...0--.4 9-10 
Passing Parameters for Program Menus .................... 9-10 
Building a Program Menus... ww we 9-11 
Exiting from a Program Menu without Returning to the Previous Menu. .. 9-13 
Avoiding Menu Name Conflict ................ 2.200200 008. 9-15 
Naming YourMenus ............ 2.0000 pee ee 9-15 
Placing Your Menu in a Higher Library in the Library List .......... 9-16 
Specifying the Library That Contains the Menu ................ 9-16 


Contents Vii 


Using the Generic Menu Specification ..................... 9-16 


Changing the Command Default after Duplicating a Command ....... 9-16 
Displaying Menu Attributes ...... 2.0.2.2... 0.00002 ee 9-16 
Changing Menu Attributes ........2...2....2.2 0.00020 02000. 9-16 
Deleting Menus! «2 2yeseaee ceed hi SENN YASS Se ae OLE Eas 9-17 
Chapter 10. Using User-Defined Data Streams ................ 10-1 
Understanding Display Station Differences .................... 10-1 
Understanding User-Defined Data Stream Limitations .............. 10-2 
Chapter 11. Passing Data between Programs ................ 11-1 
Passing Data in the Same Routing StepinaJob ................ 11-1 
Passing Data between Routing Steps inaJob .................. 11-3 


Chapter 12. Waiting for Input from a Display File, an ICF File, and a 


Data: Queue. «25 sv ki eee Gy ee EG ae ee eee ee EN 12-1 
Chapter 13. Using Alternative Character Sets and Code Pages... . 13-1 
Specifying Character Translation for Fields .................... 13-2 
Determining the Character Identifier (CHRID) Value for Your Display .... . 13-4 
Chapter 14. Improving System Performance with Displays ........ 14-1 
Deferring the Write Operation fora Display File ................. 14-1 
Designating the Primary Screen Size for a Display File ............. 14-1 
Writing Only One Page of Subfile Records ata Time .............. 14-1 
Sharing an Open Data Path (ODP) forthe Same Job .............. 14-2 
Sending Records with Input Fields to the Display in Order ........... 14-2 
Overlapping and Not Deleting Repeatedly Sent Records ............ 14-2 
Restoring the Display ............ 00.000. ee 14-3 
Defining Command Attention Keys Rather Than Command Function Keys . 14-3 
Using the Invite Operation ...........2..... 02.00.0002 00004 14-3 
Using Windows .... 2... 2.0... 14-4 


Part 3. Programming Application Displays Using Panel Groups 


Chapter 15. Improving Productivity with User Interface Manager .... 15-1 
Increasing User Productivity ........... 2.0.0.0. 0 2 eee 15-1 
Increasing Application Programmer Productivity ................. 15-1 
What to Consider before Using UIM Instead of Data Description 

Specifications (DDS) ............ 0.200000 2 ee 15-1 
Chapter 16. Introduction to the User Interface Manager .......... 16-1 
Overview of UIM  .. 1... ee 16-1 
What the UIM Supports ................ 020000022 eee 16-2 
What Isa Panel Group... 2... 2. 16-2 
WhatIlsaMenu ........... 0000 2 16-2 
Creating Objects ... 2... 2.0... ee 16-3 
Elements Withina Panel Group ..........2....2..22.2000004 16-3 
Using the UIM Language Tags ............. 2.000000 eee 16-4 
Using Dialog Commands ..............-.0 0.000000 16-4 
Using Control Language (CL) Commands ...................-. 16-5 
Using an Application Programming Interface (API) ............... 16-5 
Defining a Menu Object Using UIM ...........2.2......2.0.-. 16-6 


viii Application Display Programming V4R1 


Creatinga Menu Panel ............2.2.0 0000000020 16-6 


Required Tags fora Menu Panel ..................20004. 16-8 
Source for Example Menu .............-...222000500004 16-9 
Defining a Panel Group Object Using UIM  ................... 16-13 
CreatingaList Panel ............2..0.0.0 0000000022 16-13 
Required Tags foraList Panel ...................20.0.. 16-16 
Source for Example List Panel .....................00. 16-17 
Application Programming fora List Panel .................. 16-25 
Creating a Confirmation List Panel ....................00.. 16-27 
Required Tags for a Confirmation List Panel ................ 16-28 
Source for Example Confirmation Panel ................... 16-28 
Automatic Confirmation Processing ..................-04. 16-31 
Application Programming for Confirmation Processing ........... 16-31 
Creating a Data Presentation Panel ...................00.. 16-32 
Required Tags for a Data Presentation Panel ................ 16-34 
Source for Example Data Presentation Panel ................ 16-35 
Application Programming for a Data Presentation Panel .......... 16-46 
Data Entry Panel ... 2... 2... 16-49 
Creating a Panel witha Menu Bar .....................-4. 16-50 
Required Tags fora Panel witha Menu Bar ................. 16-52 
Source for Example Panel witha Menu Bar ................. 16-53 
Application Programming fora Menu Bar Panel .............. 16-63 
Chapter 17. Details of Using User Interface Manager ............ 17-1 
Opening a UIM Application ...........2...2.2. 0.200200 2000. 17-1 
Defining Dialog Variables ............. 2.000.000 2004. 17-1 
Restrictions on Using Dialog Variables ..................... 17-3 
Dialog Variable Error Messages ..................020000. 17-3 
Providing Field Values for a Display Panel Using Dialog Variables .... 17-4 
Using Variable Pool Services .............. 2.000005 000 8 17-4 
Character Set and Code Page Considerations ................ 17-5 
Managing‘a EISt’ ¢. 2... keg oe Mond ak ee ee Oe ha Ew eS be 17-7 
Defining a EISt. amet sa bee tera ae ed ace Beds vit ease es BO ees 17-8 
Initializing: a ISt «a4. fa eoiaG ake ee a Oe Pea a be ew ae 4 17-8 
DisplayingaList ....... 0.0.0.0... 00 ee 17-8 
UpdatingaList ......... 00.00.0000 17-9 
Incomplete List Processing ............. 2.0000 eee eee 17-9 
Removing and Inserting an Entry froomaList ................ 17-10 
Controlling List Entries ona List Display ................... 17-10 
Improving Interactive Response Time for a List Display .......... 17-11 
Using Action Lists and Selection Lists .................... 17-11 
Using Selection Characters ............ 0... 0000. eee ees 17-13 
Managing Panel Functions ............ 0... 000002 eee 17-13 
Enabling ConversiontoaGUI .....................20005 17-14 
Scrolling Support ........0...0 00000 ee 17-14 
Defining Scrollable Areas... 2... ee 17-14 
Defining Function Key Scrolling ..................2...004. 17-15 
Scrolling and Error Conditions .....................20.. 17-15 
Scrolling a List Area ........2... 202000200200 ee 17-15 
Scrollinga Menu Area ............0 002002 eee 17-16 
Scrolling an Information Area... 2... 2... 2. 2 17-16 
Scrolling Data ltem Groups ...............20.200 2000. 17-16 
Scrolling a TextArea ........2... 020002000200 17-16 
Defining Contextual Help ................ 0200000220005 17-16 


Contents ix 


Command Line Restrictions ..........0.0..00200022.000000008. 17-19 


Command Line Interpretation ..................2..220.. 17-19 
Entering Commands That Are TooLong ................... 17-20 
Defining Function Keys ... 2... 20.0.0 00 ee ee 17-20 
Formatting Function Keys ............. 220000 eee eee 17-20 
Handling Function Keys and VARUPD Value ................ 17-21 
Panel Formatting Concepts .................0. 000220005 17-22 
When Panel Formatting Is Performed .................... 17-22 
Application Control of Panel Formatting ................... 17-23 
Limits of the Panel Formatter .................0..20004 17-24 
Folding Up Multiple Panels When EXIT Is Requested ............. 17-24 
Folding Up aList Panel ...............2..2..2......2.... 17-26 
Adding a Pop-Up Window over Another Panel ............... 17-27 
Using’Menu: Bars: cso eae pe a Ra ee a ee a ee ie 17-27 
Differences Between Pull-Down Menus and Pop-Up Windows ...... 17-28 
Using Pop-Up Windows ............ 0.000 eee 17-30 
Defining Application Windows ................... 22008. 17-30 
Adding and Removing Windows ................22.2008. 17-31 
Using the Command Line ina Window .................... 17-32 
UIM as a Request Processor Program When Displaying a Panel ...... 17-33 
Printing Concepts ............ 200000 17-33 
Printing a Print Head Panel ............0..22... 0.022004. 17-35 
Printing a PrintPanel ............. 0... 20000000 2a, 17-35 
Using Blank Lines for Separating ......................-. 17-36 
Fonts and Highlighting ............... 2.20002 eee 17-36 
Printing the Trailer 2... 2.0... ee 17-36 
Defining Prolog Areas... ww 17-36 
Defining Header Areas... 1... 2... 17-36 
Using the Page-Eject Function During Printing ...........2.2... 17-37 
Sharing and Overriding Printer Files ..................... 17-37 
Printing Double-Byte Character Set (DBCS) Considerations ....... 17-37 
Commonly Asked UIM Questions ...................000. 17-37 


Part 4. Programming Help Displays 


Chapter 18. Making Online Help Information Accessible for Your 


Display File: - 6 whe fendi oes ee Ae Ee ee ee a 18-1 
Enabling the Help Key ........... 2.0.0.0 0 2p 18-2 
Choosing between Panel Groups, Documents, and Records for Help .... 18-2 
Defining Which Areas of Your Display Need Online Help Information .... . 18-3 
Specifying Panel Groups for Help in Your Display File ............. 18-6 

Copying QUSRTOOL Examples That Specify Help Using Panel Groups . 18-9 
Specifying Documents in Your Display File .................... 18-9 
Specifying Records in Your Display File ..................... 18-12 

Entering the Records That Contain the Help Information ......... 18-14 

Using Records and Documents for Help in the Same Display File .... 18-15 

Understanding the Restrictions on Records ................. 18-15 

Paging between Help Displays That Use Records ............. 18-16 
Returning Control to Your Program after Pressing the Help Key ...... 18-20 

Returning Control to Your Program after Showing the Help Display ... 18-20 

Returning Control to Your Program without Showing the Help Display . 18-22 
Chapter 19. Making Online Help Accessible for Your Panel Group ... 19-1 


X Application Display Programming V4R1 


Definitions and Explanations ............. 0000002 ee eee 19-1 


Help inaListArea .... 2... . 19-5 
Coding: Help “ae. see eRe ated GS adete wae wee eS ele ead 19-6 
Help ina Menu Area ... 2... 19-7 
Goding Help: 23 2s. SNe ee SS ee eh SES SRA RES Se Ae eR 19-7 
Help ina DataArea ...... 2... . 19-9 
Coding Melb: 43 ise eis ae ee ei pecan alee Sree aeRO 19-10 
Help ina Menu BarArea .... 2... 19-13 
Coding GIO. - rte oe ehh edn tae choy Sm, tetahttens sh dee eas argue are 19-14 
Help in a Function Key Area... 19-15 
Godinig: Help: cn ace as an eee OWL Pee SG UG eee a Dobe 19-16 
Chapter 20. Defining Online Help Information ................ 20-1 
Defining Online Help Information ina Panel Group ............... 20-1 
Entering the UIM Source for a Panel Group for Help ............. 20-1 
Creating and Deleting Panel Groups ..................... 20-15 
Assigning Panel Groups as Help for Commands .............. 20-16 
Using Panel Groups ina Search Index .................... 20-16 
Copying QUSRTOOL Examples That Define Help ina Panel Group .. 20-18 
Defining Online Information ina Document ................... 20-18 
Creating a Document forHelp ..............-..-2.02204. 20-18 
Viewing the Document without Pressing the Help Key ........... 20-19 
Defining Online Help Information ina DDS Record .............. 20-19 


Part 5. Guidelines for IBM AS/400-Style Displays 


Chapter 21. Designing IBM AS/400-Style Displays ............. 21-1 
Using the Displays Example in the QUSRTOOL Library ............ 21-1 
Recognizing the Example Objects ....................-.. 21-1 
Installing the Example Objects ................ 0.220000. 21-4 
Viewing the Sample Displays, Command, and Online Help Information .. 21-4 
Copying the Source for the Example Objects for YourOwn Use ...... 21-7 
Defining Special Functions and Attributes for All Displays ........... 21-8 
Designing the Single-Choice Menu Display .................... 21-8 
SPITS: © abcneas teed clit ce atid dg nar patace nerd ae lol, on doy a opin ata ah od it boa at 21-9 
Instruction Line»... 21-9 
Menu Options: .¢ 6... 48a Bee ee ek S MOOS PERE Pee EAS 21-9 
Menu Selection Entry Field .....................2.0.044 21-10 
FUNCtION: KEYS! sa ew a we ae RA ASE ee te bo 21-10 
Online Help Information ................0 020020020005 21-10 
General Menu Display Operation .....................0.. 21-10 
Designing the Entry Display ............... 000000000000. 21-11 
WMIGS St he tthe Oh ec Ness, tance Aor ho ag a Ropes hoes Seneca 21-11 
Instruction Line...) 21-12 
PFOMPUATCA seg ge ws Ao ands eked tok Ghee Selo aneta nhesd ue ates a 21-12 
FUNCTION: KEYS>*-i6 es Sh sre ee eat Ee Sted, bY Wee he 21-17 
Online Help Information ................0 02002002000. 21-17 
General Entry Display Operation ...................2... 21-17 
Designing the Information Display ....................0004 21-17 
Witles <euh4 ett Genie Oi Si Bot et oe Na ei: oe dB 21-19 
Location Information .......... 0.0000 pee 21-19 
PrompliArea: 1: ws. a a4 bale haem le ee he EP a yo 21-19 
PrOMPUATCA:2: ga oka PS S$ bob bd oe Oe ee le ele 21-20 


Contents Xi 


Instruction ING: cu. 2 ease ie nek EN a ee Be See 21-20 


Function K6yS> 4. eee aed aa he Ae BO ee a a A 21-20 
Online Help Information ................ 02002002000. 21-20 
General Information Display Operation .................... 21-21 
Designing the List Display ............... 0.0.0 000 000005 21-21 
TATIG.: Sct ssecn se of A Oe AR Ae Mal at hn oe hy ON Sh de gs toe 2 fd 21-22 
POMPLATeay 5. to Sitesi a ig ae! 2 eit eae ee bite ak Be eee 21-22 
Instruction Lines <-a..4-648 8 oe wdhie Bh ee nS es ee 21-22 
OPONSWING H's. Seis ert sed hors Recap fe Spal Bnet Ae tiles A oo 21-23 
Column Headings ............. 000002 pee ee 21-24 
Extended Action Entry Area... 2... 2. 2 ee 21-24 
List:FieldS:. «32 2.2 eee ecw i 6-8 et Bh ee Oe ee Re 21-24 
Paging Location Information ..............2.0 00022008. 21-25 
FunCctONn KeYS™. 2 eet bate od ee aes en pe he et, 21-25 
Online Help Information ................ 02000002000. 21-25 
General List Display Operation ....................2.0.. 21-26 
Defining the Function Key Area for All Displays ................ 21-33 
Optional Command Line and Identifier Field .............2.... 21-34 
Common Key Assignments .............. 202005002202 21-38 
Defining Help Information for All Displays .................... 21-44 
Help forthe Menu Display .............. 0.000000 eee 21-44 
Help for the Entry Display .............. 2.20.00 000 00004 21-46 
Help for the Information Display ....................0004 21-47 
Help forthe List Display ............. 0.0.00 00002 2b eG 21-48 
Defining and Presenting Messages ..............000000005 21-49 
Designing Common User Access (CUA) Entry Level Models ........ 21-50 
Entry Dialog;ActionS 2:4 seme eed ee Ee 21-51 
Single-Choice Selection (Menu) .............-..2..22005 21-52 
Entry Display® oo 1 Sk seh ee Ga Se Bed kh Ade ue Be ee ae bE 21-53 
Information Display .......... 2.00000 ee 21-55 
List:DISplay. «S45 i tice pews, artis eaten a he A PA ae ea ha ke oe hte 21-55 
Help Information .. 0... ....0 0.0 2 21-57 
Part 6. Appendixes 
Appendix A. UIM Panel Group Definition Language ............ A-1 
Panel Group Organization ..............0.00 20200200208. A-4 
Name:Syntax:~ s62-6 a4c8 Bd REG Soe ae bh oe © eon Wapae aed A-4 
SYMDOIS? .° 2 at Utes he See ale gs Slee Poise s SPs aed A-5 
Comments: 3 4. ao-ny be ew RS A eA BERR ee BSE A-6 
IIMDGOOS: © aha od ate dah de tid dard oy Gena d dob ae ew a a ee A-6 
DBCS Graphic Literals .........2...... 02.00.20 0200 008. A-6 
Hexadecimal Literals .. 2.2... 0.0.2... A-6 
APPFMT (Application Formatted Area) .................02000.% A-8 
Required Attributes 2... 2... 0... A-8 
Optional Attribute .........02.2. 20200200000 2 es A-8 
Application Formatted Data ............... 2.00.22 20000. A-9 
Example: Application Formatted Area ..................0.4. A-9 
BOTINST (Bottom Instruction) ..................200.200004 A-10 
Optional Attribute .........0.2.2 002000002 es A-10 
Optional’ Text: 2.2 e heh ach pt GR oe do ack ene Od tee ed A-10 
CHECK (Validity Checking) ............. 20.00.0000 200 eee A-11 
Required Attribute 2... 2... 0.00.20... A-11 


xii Application Display Programming V4R1 


Optional Attributes: 2.0 cg. Bae ee a PE a we A-11 


Example: Validity Checking ................ 220202000045. A-12 
CIT (Title Citation) ........02.. 02.0020 0000022 ee A-13 
Optional Text. s:c4. 429 2A but oad Ae BG 4 ee ERE ae weed A-13 
Example: Title Citations .................0 202020200004. A-13 
CLASS (Class Definition) .................. 202002002000. A-14 
Required Attributes ...... 0.0.0... 0.02 A-14 
Optional Attributes .........020220 202.002.000.002 eee A-18 
Example: Class Definitions ....................2...04. A-24 
Display Forms of Numeric Values .................220000. A-24 
Display Forms of Character, Date, and Time Values ............. A-25 
CMDLINE (Command Line) ................. 02002002000 A-26 
Required Attribute ... 2... 0.0.0... 02 ee A-26 
Optional Attribute .......2..2.202020 2002000000 ee A-26 
Optional Text 2o+ 4.4.63 oGok we doe Ae oO Red eee Bo as A-26 
COND (Condition Definition) ....................2....00.. A-27 
Required Attributes ........ 0.0... 00002 ee A-27 
Optional Attribute .........202..02. 2.02.00 000 2 eee A-28 
Example: Conditioning an Option .....................04. A-29 
COPYR (Copyright) .......... 0.000000 ee A-30 
Required Text 2... 2... ee A-30 
DATA (Data Presentation Area) ........... 0.00000 e eee A-31 
Required Attribute 2... 2... 0.0.0... 0. A-32 
Optional Attributes .........2.22. 2.200.000 0 02eeees A-32 
Optional Text. 5) oy oe ee a ee eee 24 A-33 
Print Formatting Considerations ..................2..204. A-33 
Example 1: Data Entry Panel ............2.2.......2000.. A-34 
Example 2: Two-Column Format ina Data Entry Panel ........... A-34 
Example 3: Two Presentation Areas for Dataltems ............. A-35 
Example 4: Data Presentation Area witha Menu Area ........... A-36 
Example 5: Data Entry Panel with a Nested DataGroup .......... A-36 
DATAC (Data Item Choices) ................2. 2000500004 A-38 
Optional Attribute .........02020 202.002.0000 ee A-38 
Optional Text. 2.2 22% Awe G ike Ade Gale ow h aoe Eke PES A-38 
DATACOL (Data Column) ................ 2.200220 0500004 A-39 
Required Attribute 2... 2... 0.0.0... 00 A-39 
Optional: Texts 2.3. jae Se eS oan ee ean ee ee Pe eae ead A-39 
DATAGRP (Data Group) ............. 20200000220 eee A-40 
Optional Attributes ...........020 2020020002 ees A-40 
Optional Text. «25 6 4 owe ee oy ee ee eee Ae ee 4 A-41 
DATA (Datanltem): “v5 35 Ssh ashe a GR Ee ee ee aye. ak BS A-42 
Required Attributes 2... 2... 0.0.0.2... 002 A-42 
Optional Attributes ..........2..02.2. 002000200022 eee A-43 
Optional Text? «4.0.4. ba ase han Sie ie eet Phe a Sa ee ot es A-45 
DATAIX (Data Item Extender) ............. 0.000000 2 eee A-47 
Required Attributes ...... 0.0.2... 00.2 A-47 
Optional Attributes .........0.2.200 202.002.002.002 eee A-48 
DATASLT (Data Selection Field) ......................0..-. A-51 
Required Attributes ........ 0.2... 00.2 A-51 
Optional Attributes ..........2.2.2.2. 00200020002 ee A-51 
Optional Text. “2.0% gad ania, Gi eweoesh Awe Be oe eee dhe A-52 
Example 1: Data Entry Panel ............2.2.......22.00.. A-53 
Example 2: Multiple-Selection Field ...................... A-53 
DATASLTC (Data Selection Field Choice) .................... A-55 


Contents Xtii 


Optional Attributes ..........202 0020020000 es A-55 


Optional! Text 222. ase ee ee ER AGS en Moe eee a oA eA A-56 
DL (Definition List) ............. 00000200000 eee ee A-57 
Optional Attribute ..........202 002.0000 02s A-57 
Required TagS .. 1... A-57 
Optional Tags. 2.4 es hoe ee a a a eee ed Ee eek A-58 
Example 1: Definition List ..............2........2000.. A-58 
Example 2: Compact Definition List ...................... A-58 
PIG: (RIQUIC). 27530 caus es cies eed Soh Stel eg ee eter ie gh ee Se A-59 
Optional Attribute ..........2.2 00200200000 A-59 
Optional'Tag:. « ¢0:0.6 ees hb oS hee bu W eee dee hed A-59 
Example: Sample Figure ...............0. 2000200200. A-59 
HELP (Help Module) ..............-. 2.02000 eee ee A-60 
Required Attribute .. 2... 2.00... 02 ee A-60 
Optional Attributes .........02.200 2020020000022 eee A-60 
Optional Text = 4 3. cw acda aE Soe Ws SE ERO Be ae Ee A-61 
Example: Help Panel Definition ...................2.0... A-62 
HPO through HP9 (Highlighted Phrase) ................2...0.. A-63 
Optional: Text> =. 22 Shae eho eR AG od Sie BE eee a ed Eo A-63 
H1 through H4 (Heading) ............ 00.000 ee A-65 
Required Text) 4 ek eee aa he Sb Se eee as Gee Gee A-65 
Example: Heading Tags ............. 2.000 e eee eee A-65 
IMHELP (Imbed Help) ............... 0200000 eee ee A-66 
Required Attnibutes: «4.45: ck ed ete ek & aca) Sneha Gis A we Gs aa A-66 
Example: Imbedded Help .............. 220000022 A-66 
IMPORT (Import) ........... 0200000 2c ee A-67 
Required:Attributes: «ss eee ee a eee ee eee A-67 
Optional Attributes ..........202.0 202.002.0000 2 eee A-67 
INFO (Information Area) ........-220 020002002 ee A-68 
Required Attribute .... 2... 0.0.0... 00 2 A-68 
OptionalPAttributes:. ic 2g. es ee Re LE EE ee BS A-68 
Optional Text: .s.494 gon A ee OE Gao bee ee A-68 
Print Formatting Considerations .....................204. A-69 
ISCH (Index Search) ..........0 2.000002 ee ee A-70 
Required Attribute 2... 2... 0.00.02. A-70 
Required Text 2.2... A-70 
Example: Index Search ........... 0000000020 eee A-70 
ISCHSUBT (Index Search Subtopic) ......................-. A-71 
Required Attribute: ica tee eat eh oad See ae! Ae Qa g A-71 
Example: Index Search Hierarchy ....................-0.. A-71 
ISCHSYN (Index Search Synonym) ..................200004 A-72 
Required Attribute ... 2... 00.2 A-72 
Required Text. <a. sna Gee 48 deka naa oe gota be Glas Ba ded Sw Glhac A-72 
Example: Index Search Synonyms ...................+204. A-72 
KEYI (Key List Item) .............. 2.020000 02 eee eee A-74 
Required Attributes ... 2... 0... 00 ce ee A-74 
Optional Attributes .........0220202. 00200000022 eee ee A-75 
Optional Text: 4-444. he ee Pe Be Ee eas ee Pe ee ee A-75 
Example: Key Definitions .................0 0.2220 000. A-75 
KEY.E(Key- List): a: 2 beac a bose etwas AS ie ee Se A-76 
Required Attribute .... 2... 0.00.20... A-76 
Optional Attribute .........02.20 2020020002000 2 ee A-76 
Example: Key List. on saauie eee AG a ie Re ee ee BA ee A-76 
LINES (Unformatted Lines) ................ 2.20.00 0200054 A-77 


XIV Application Display Programming V4R1 


Optional Text eda sea eRe A ea BD Pe ae we A-77 


Example: Unformatted Lines ....................20004. A-77 
LINK (Hypertext Link Definition) ....................2000.. A-78 
Required Attribute .... 2... 0.0.0... 00 2 A-78 
Optional Attributes .........02.20.02.2.0 020002000220 eee A-78 
Conditional Expressions .............-.. 2000000502 A-79 
Bidirectional Considerations .....................2200-4 A-80 
Example: Hypertext Link .............. 2.200000 020 eas A-80 
HIS (EIstAtea)s scat: > senitheet se cdtee. hte: de Se oGtot aes eee eee opt Ge A-82 
Required Attributes ....... 0.0.00 0c ee A-83 
Optional Attributes ..........022.02.2 00200000022 eee A-83 
Optional Text. «ao: ow ate ee Be oe Eee hee ee oe A-85 
Print Formatting Considerations ....................2204. A-86 
Example 1: ListArea .. 2... 0... A-86 
Example 2: List Area with Three Layout Columns .............. A-87 
Example 3: List Area with List Column Groups ................ A-87 
Example 4: Dynamic List Column Heading Formatting ........... A-88 
LISTACT (List Action) .........2.2.. 202000000002 eee A-90 
Required Attributes 2... ... 0.0.2.0. 00. A-90 
Optional Attributes .........2.2.202.2 0020000002 eee A-91 
Optional Text «44 40% oa eee eae BST SAS eee he Y A-94 
Confirmation Panel Requirements ....................+-. A-94 
Confirmation Panel Conventions .....................--4 A-94 
Example: List Actions ........... 2.0000 eee ee A-95 
LISTCOL (List Column) ...........2.2.0 0200000000022 eee A-96 
Required Attributes 2... 2... 0.0.0... 000. ee A-96 
Optional-Attributes: . «2 ges. pegs Bi wve se aoe oo are ee A A-97 
Optional Texts 2° 402 sa 4 kere hgh ol aed ele Godek EGG aoe we A-99 
Formatting Considerations ................. 2000200008. A-99 
LISTDEF (List Definition) .................02.0 02... 200.. A-100 
Required Attributes ....... 0... 0020 ee ee A-100 
Optional Attributes ..........02. 0200002000002 eee A-100 
LISTGRP (List Column Group) ...............0-0. 2002000. A-103 
Required Attributes ........ 0.2... 0000 A-103 
Optional Attribute ......... 0202202200000 00200 eee A-103 
Optional Text, 04.29 G4 aE ORS AAR DEERME ARR RRR He A-104 
Example: List Column Group)... 2... 2 A-104 
LISTVIEW (List View) ..........2...0 0000000020 0c A-105 
Required Attribute ... 2.2... 0.00... A-105 
Optional Attribute ..........2.2. 20000200202 ee A-105 
EP (EISTP AM). 32. G cite Som fe Sieh ees el one ae Se wh eek aye ak A-107 
Example: -List:Part 2 asn ba eaae oi ev ene eR EAE heals A-107 
MBAR (Menu Bar) .........0. 0.00200 2 ee A-108 
Required Attribute 2... 2... 0.00.20. 000 2 A-108 
Optional Attributes ...........02.0 2020000200200 eee A-108 
Example: Menu Bar ............ 00000 eee eee A-108 
MBARC (Menu Bar Choice) ................ 020020022 ee A-110 
Required Attributes ......... 0... 000002 A-110 
Required Text 2... 2... ee A-110 
MENU (Menu Area) .. 2... 2 A-111 
Required Attribute ©... 2... 0.00.00. 0. A-111 
Optional Attribute 2.2... 0... .2.220 22000000020 2 ee A-111 
Optional Text .c.4 hk a Ge ke od a SP OG ee EES OO A eS A-112 
Example 1: Simple Menu Area ..................22205. A-112 


Contents XV 


Example 2: Menu Area with Groups ..................--. A-112 


MENUGRP (Menu Group) ...............-20 0200202 eee A-114 
Optional Attribute 2... 2.0.2.2... 2.220 2020000000200 2 ee A-114 
Optional Text? «+ 24215 .he wae RRS Pee EAE eee oe 4S ee A-114 

MENUI or MI (Menu Item) ............. 0.202000 00022 ee, A-115 
Required Attributes ......... 2.2... 000. A-115 
Optional Attributes ..........2.2.202. 002020020022 eee A-115 
Optional Text .. 2... 0.2.00 20.0000 2 ee A-116 

INSPZORNOVTE NOG): ccc ecte je sknd ten Geist <b Soetal gneehene dans, bles 5 an oss A-117 
Optional’ Text: 6 a.t2naibepaddad tate eae gad teloe ae ea A-117 
Example: UsingaNote .............. 2... 00000 eee A-117 

OL: (Ordered: List) o so2 4 ete ei ag ae Bled Bae ee Ea ew ORS: A-118 
Optional: Attribute? anc.) pa 2k ween ooo ae Re OEE ede we alle A-119 
Required Tag: unete cp eae) Ye ce yp ease pe hy ee fed, A-119 
Example: Ordered List ............... 20200200220 005. A-119 

OPTLINE (Option Line) .........2.20 202.0000 00002 ee A-120 
Optional Attribute 2... 2... ....2.200 220000200200 2 ee A-120 
Optionaliiext! 22 gusts ke NS ee ee ev oe Be ea eS A-120 

P (Paragraph) a.) 298 Gea ee ee oe de Fe Se ee ota ee © BS A-121 
Optional Text .. 2... 0.2.0 020002 A-121 
Example: Paragraph Tag ......... 2.0... 2 eee ee A-121 

PANEL (Display Panel) ............. 2.000000 eee ee A-122 
Required Attributes .......... 2.20.00 002 A-122 
Optional: Attributes... ..-2c24 6. ko el ca a Gs A-123 
Optional Text .. 2.2... 2.00.00 2 A-127 
Example: Panel Definition ...................... 20048. A-127 

PARML (Parameter List) ........... 2.000000 eee eee A-129 
Required Tags). cicath boa debe a Wana GGA So Badd ea gee A-129 
Example: Parameter List ...............2 0000022008. A-130 

PC (Paragraph Continuation) ....................2. 220005 A-131 
Example: Paragraph Continuation ...................... A-131 

PDACCEL (Pull-Down Accelerator) ..................2005. A-132 
Required Texte doce page OES elie ae iene i ea A A-132 

PDFLD (Pull-Down Field) ..................0.000 220005 A-133 
Optional Attribute 2... 2.2... 02.0020 00000000 ee A-133 

PDFLDC (Pull-Down Field Choice) ...................-2..-. A-134 
Required Attributes ........0 2.0.00 00 ee A-134 
Optional Attributes ..........2.2. 2020000200000 ee A-134 
Optional Text. 542s tee aexteteaesd brane fe op aad nent seetdany ties foo Si A-136 
Confirmation Panel Requirements ..................-... A-136 
Confirmation Panel Conventions ..................2204. A-136 

PK (Programming Keyword) .......... 0.0000 eee ee A-138 
Optional Attribute ..... 0.2... 202 2.002000 0 2 A-138 
Required T6xt. aca ste oR De bE DEO ee eek a ed A-138 

PNLGRP (Panel Group) ................. 200000000200 G A-139 
OptionalbAttributes’ 20.64 2.45 ee ee EA Oe ee SERS a A-139 

PRTHEAD (Print Head Panel) .....................20005 A-142 
Required Attribute .... 2... 002... 06 A-142 
Optional Attributes ..........2.202. 2020000200200 2 eee A-142 
Optional Text .. 2.2... 2.2.0 02000000 2 ee A-143 
Layout of the Title Lines .............. 0.2.00... 0 0004 A-143 
Example: Print Tile Line .................0 0.022004. A-145 

PRTPNL (Print Panel) ............... 2... .000 0000020005 A-146 
Required Attribute: sic sacs -esecgey elle ho acd) enn Bla @ ara A-146 


XVI Application Display Programming V4R1 


Optional Attributes ..........2022. 0200020200200 2 eee A-146 


Optional Text. 2a sas SARS MAS RARE AS OAM eee mae So A-146 
PRTTRAIL (Print Trailer Message) ............. 0.00000 0005 A-148 
Required Text) acca eg haa ed Ao Da a ee Mek eR ww A-148 
Example: Trailer Message .............. 2.00000 A-148 
PV (Programming Variable) ............ 2.0.00 002 eee A-149 
Required: Lext © o:c.n Sse ei kes SRS eee eee bea Gack G A-149 
RT (Reverse Text) 2... 0... ee A-150 
Example 1: Left-to-Right Formatting on a Right-to-Left Panel ...... A-150 
Example 2: Left-to-Right Formatting on a Left-to-Right Panel ...... A-151 
SL.(Simplé: List), esac sab WA ate ha oe whe Bee ae es Soe A-152 
Optional:Attribute: cee ba eee ed Bh ee eae ed he A-152 
Required: Tage: “hata we eter eka lee bd ae bee a ee es bdo A-152 
Example: Simple Lists ................2.0 20200200005. A-153 
TEXT (Text Area) 2... A-154 
Required Attribute ©... 2... 0.0.0... 00 2 A-154 
Optional Attributes ..........2020 2020002020020 022 eee A-155 
Cursor positioning .............0 00000 ee A-155 
Text Data, af eta te GR ed ad OR Da eae ane a ae a A-155 
Example: Textarea 2... A-157 
Tl (Translation List Item)  .. 2... 0.0.02. 2 A-158 
Optional Attribute .. 2.2... 2.2.00 2. 200000002 ee A-158 
Optional Text ... 2... 20020200020 2 ee A-158 
FE Chiranslation: Dist): 5-35. saat eee Gane Be i eee gin A-159 
Optional Attributes ..........2.2.0 2.2.0.2. 020022 ee A-159 
Examples: Translation List ................. 0.022004. A-159 
TOPINST (Top Instruction) ..............0 02002002222. A-161 
Optional Attribute 2.2... 0.2.0. 2.202. 200000002 2 A-161 
Optional’ Text 6x v4.4 deh ine eon ee ae Ba a ae nd A-161 
THe CEruth: Fable). 28 43 oe edo ake OG BON DO e ea eye GOe a4 A-162 
Required Attributes ... 2... 0.0.00 20 ee A-162 
Example: Truth Table ............. 0... 00000022004 A-162 
TTROW (Truth Table Row) ...............20 0200000005. A-163 
Required Attribute .... 2... 0.0.0... 000 A-163 
UL (Unordered List) .......... 2.0.00 00022 A-164 
Optional Attribute ..........2.220 220000200200 2 ee A-164 
Required Tag: 4-.i 4%. ba ae eS Sate aS eae Pe ee be A-165 
Example: Unordered Lists ................ 0000002008. A-165 
VAR (Variable Definition) ................20 20200200005. A-166 
Required Attribute ©... 2... 0.0.0... 00 0 2 A-166 
Optional Attributes ..........2.20 0202020200200 eee A-166 
Dialog Variables Defined by UIM  .............2.......... A-166 
VARRCD (Variable Record Definition) ...................... A-169 
Required Attributes .........2.2.2.2.2.2.2.2.2..0 2000000028 A-169 
Optional Attributes ..........2.20.0 02.00.20 0200 ee A-169 
XH1 through XH4 (Extended Help Headings) ................. A-170 
Required Text 2... 2... A-170 
Formatting Rules... 2... A-170 
Example: Sample Headings ...................222205. A-170 
XMP (Example) ..........00 00 A-171 
Example: Formatting an Example ..................20.. A-171 
Appendix B. UIM Dialog Commands ...................... B-1 
The VARUPD Attribute ............ 00.2.2... 00022 ee B-4 


Contents XVii 


xviii 


ACTIONS (Menu Bar Cursor Action) ..................2... B-4 


CALL (Call Program) ........22..0 202000002 es B-4 
CANCEL #34.) 2 Me ie ee hs Gah oot ee oa ee Oe Fee B-6 
CHGVIEW (Change View) ............-...00 0000500004 B-6 
CMD (System Command) ............-....0.2000500004 B-7 
CMDLINE (Command Line) ...........-...2..202220004 B-7 
DSPHELP (Display Help) ................. 2.200200 008. B-7 
ENTER. gC te tint air tee ed ek ee es eat cae AN ta ah act B-8 
EXD (ExitiDisplay)> <o.t943-c< fen de unte-ok a etal Gases tence he Gane B-8 
EXTHELP (Extended Help) ..................20 002005. B-9 
HELP? var echt os went owe Ce Se ote eee Bute e B-9 
HELPHEEPS... 6 otis et ce on oe a 48 Ge PE ee he Fao B-9 
HEEPIDX, 4: 2%, & ovate d At WS no enee are ae Mates eG) hot art ta Be Meee B-9 
HOME (Display Home Menu) ................-.2..+22004 B-9 
KEYSHEEP® «sag phot ud $akt GR dod ii ee Ok ER B-10 
MENU) 3 ao ad eh Pe Pale ss Le ee ene oe ee B-10 
MOREKEYS (Display More Function Keys) .................-. B-10 
MOVETOP (Move to Top) ................00 2000500004 B-11 
MSG (Display Message) .............-0 020020002 eee B-11 
PAGEDOWN) 22. tatty ot A ed Ba eee Gee ae Bie oan Gee B-11 
PAGEUP® je ah acevo Gere, oii nt os ea Ba Oh a tee aces Yes a Bee, Greg B-12 
PRINT (Print Display) .............0 0.0.20 0 0 ee B-12 
PROMPT: ; a: te ts0 ver Wp eruietins sigeTh se a see a ie oe eae ged B-13 
PULLDOWN (Display Pull-Down Menu) .................... B-14 
RETRIEVE (Retrieve Command String) .................... B-14 
RETURN (Return Control to Application) ................... B-14 
Appendix C. Feedback Area Layouts for Display Files ........... C-1 
Open Feedback Area... 1... C-1 
Device Definition List .........2.2.2.....0. 00.000 0000050. C-4 
/@"Feedback. Area. ease 2 acs ee Ae NS SOP SE he C-6 
Common I/O Feedback Area ...... 2.2.2.2... -220 0000500004 C-6 
I/O Feedback Area for Display Files ...................... C-9 
Get Attributes 2.2... 2.002.000.0202 es C-12 
Appendix D. Double-Byte Character Set Support for Displays ...... D-1 
Double-Byte Character Set Fundamentals .................... D-1 
DBCS Code Scheme ................ 020000002 eee D-1 
Shift-Control Characters ............ 0.00.00 00022 e ee D-3 
Using Double-Byte Data ................. 002000000040. D-3 
Double-Byte Character Size... 2 D-4 
Processing Double-Byte Characters .................0.2 0000.4 D-4 
Basic:Gharacters; neces 4 oe bo ens & eo goa RG edad we Glas D-4 
Extended Characters ............. 2.00000 eee eee D-4 
What Happens When Extended Characters Are Not Processed ...... D-4 
Device File Support ..........0-2 0200002 e ee ee D-5 
Whata DBCS Filels ............0. 0.0.00 00002 eee D-5 
When to Indicatea DBCS File ......................004. D-5 
How to Indicatea DBCS File .......................... D-5 
Improperly Indicated DBCS Files .....................0.. D-6 
Display Support .... 2... .220 2.000000 2 ee D-6 
Inserting Shift-Control Characters ............... 0.220000. D-6 
Number of Displayed Extended Characters .................. D-6 
Number of Input Fields ona Display ...................04. D-6 


Application Display Programming V4R1 


Effects of Displaying Double-Byte Data at Alphanumeric Work Stations .. D-7 


Effects of Displaying DBCS-Graphic Fields on Double-Byte Displays ... D-7 
Application Program Considerations .....................0.4. D-7 
Designing Application Programs That Process Double-Byte Data ..... D-7 
Changing Alphanumeric Application Programs to DBCS Application 
PROGKAMS? “Fitri fh State BUA tae ie RO te hha od tal Gi ote aS dy D-8 
DBCS Font Tables .......... 0.000002 ee D-8 
Finding Out if a DBCS Font Table Exists ................... D-8 
Copying a DBCS Font Table onto Tape or Diskette ............. D-9 
Copying a DBCS Font Table from Tape or Diskette ............. D-9 
Deletinga DBCS Font Table .......................0.. D-10 
Starting the Character Generator Utility .................... D-10 
Copying User-Defined Double-Byte Characters ................ D-10 
DBCS FontFiles. . v.06 .e4 Bae Be we a a eee oe a D-10 
DBCS Sort Tables ...........0.. 00000202 D-11 
Using DBCS Sort Tables on the System .................... D-12 
Finding Out if a DBCS Sort Table Exists .................... D-12 
Saving a DBCS Sort Table onto Tape or Diskette .............. D-12 
Restoring a DBCS Sort Table from Tape or Diskette ............. D-12 
Copying a Japanese DBCS Master Sort Table to a Data File ........ D-12 
Copying a Japanese DBCS Master Sort Table from a Data File ...... D-13 
Deleting a DBCS Sort Table .............2...........0.. D-14 
DBCS Conversion Dictionaries ............. 0... 0000 eee D-14 
System-Supplied Dictionary (for Japanese Use Only) ............ D-14 
User-Created Dictionary ................... 2200200054 D-15 
Commands for DBCS Conversion Dictionaries ................ D-15 
Displaying and Printing the DBCS Conversion Dictionary .......... D-19 
Deleting a DBCS Conversion Dictionary .................... D-19 
DBCS Conversion (for Japanese Use Only) ..................-. D-19 
Where You Can Use DBCS Conversion ............-.......-. D-20 
How DBCS Conversion Works ............. 000002 ee eee D-20 
Using DBCS Conversion ..............0 0200200050022 G D-20 
Performing DBCS Conversion ................20 0000508. D-21 
Appendix E. Display File Return Codes .................... E-1 
Major Code 00... 2. Le E-1 
Major Code 02 ©. E-1 
Major Code 03) 7. wd E-2 
Major Gode:04.# tas cto: <3 ns Suhen tae tendons tetas & Sp ahitenat mink ee ei: AA E-2 
Major Codes 08-11 6... ee E-3 
Major Code 34 «5. wd E-3 
Major: Gode:80°) #424. e032 Yigaderd eee eink Vea Ae od E-3 
Major-Gode:8t) vw s46¢ 4% var pha ee BE ee Poet eG Ghee ee A ee E-5 
Major Gode-82 2.4 t ea oe See Sie ie et Pa OR VA Se ee ee le 3 E-6 
Major Code'83.) 2 4c.284 242 eet ee ea hee keene ee SY E-10 
Appendix F. EditCodes ....................20 0.00 200.. F-1 
OS/400.Edit Codes... chek ee ee pe Ee ewe 3s Poe ey Be ee F-1 
Examples of Editing Using OS/400 Edit Codes ................. F-3 
User-Defined EditCodes  ..............0.. 0.200200 22 2. F-4 
Using User-Defined Edit Codes ......................2.0.. F-5 
Example of a User-Defined EditCode ...................... F-5 
Appendix G. System/36-Compatible Display Data Management ..... G-1 


Contents XIX 


Clearing Lines on the Display .................2. 02002000. G-1 


Input Data for Display File Records ...................0000. G-2 
Input Data from the Work Station Controller ................... G-2 
Self@Check: 2-440. Se eae OA eee bE hee SORE eee Ba OE G-2 
Returt Input: 5 22954448 oo eee BAG SEMA SSS Eee eee EES G-3 
Erase Input Fields .......2. 0.00... 2 ee G-3 
Display Attributes .. 2... 2... G-3 
Positioning the Cursor .........-.. 0.000002 G-4 
Displaying MessageS  .. ww. G-4 
PutOverrides fs a. eek, ee a eb OD tee aoe Be fonds Dae Es G-6 
Handling Signed Numeric Data ...........2.......2..20000.% G-7 
Function:Keys:. s 22 2 hae et eae 4b be ok a eR Ov a ee 8 G-7 
Help Key Considerations ..............0.0 000000002 eee G-7 
Using Command Keys to Exit Application Help ................. G-8 
Cancel-Invite Operation ............ 2.200000 002 ee G-8 
Retain Command and Function Keys .................2.02-% G-9 
System/36 Functions Not Supported ..................2000.4. G-10 
Restricted DDS Keywords/Functions .............. 2000000005 G-10 
Bibliography | fo «hen e es bee wal eo eA Ba ee wae ae H-1 
INDOX® if orgie ts oe ie tee PR ah Be hee bay Gide keen ee x-1 


XX = Application Display Programming V4R1 


Figures 


2-1. 
2-2. 
2-3. 


6-7. 
6-8. 


6-9. 
6-10. 


© Copyright IBM Corp. 1997 


Sample DDS Source for a Display File .................. 2-7 
Record Formats in the Program and on the Display .......... 2-8 
DDS for Field-Level Cursor Progression ................ 2-18 
DDS for Subfile-Level Cursor Progression ............... 2-18 
Sample DDS for Right-to-Left Display Processing ........... 2-19 
Sample DDS for Program-to-System Fields .............. 2-22 
Sample DDS for Two Display Sizes ................... 2-25 
Sample DDS for Subfiles for Two Display Sizes ............ 2-25 
Valid Placement of Records on a Screen When the CLRL Keyword Is 
NotUsed. *:5 2s teat ehh Se MR et ede ee Oy Gog oh BP a 3-6 
Wrong Placement of Records on Screen When CLRL Keyword Not 

WSOd! eee ete ep oe ea eee doa gob held te fated ee ale 3-8 
Replacing Record Formats ................ 00022000. 3-9 


Sample DDS Source Showing Use of the SLNO(*VAR) Keyword .. 3-12 
Sample DDS Source Showing Difference between CLRL and 

OVERWAY? w5 205 08 4 ela eet Ra oe oe eae BAL 3-15 
Sample DDS Source Showing Use of the PUTOVR Keyword .... 3-19 
Sample DDS Source Showing Efficient Use of PUTOVR Keyword . 3-20 
Sample DDS Source Showing Another Use of PUTOVR Keyword . 3-22 


Sample DDS Source Showing Use of the PUTRETAIN Keyword .. 3-24 
Sample DDS Source Showing Use of the PUTRETAIN Keyword .. 3-25 
Sample DDS Source Showing Use of the DSPMOD Keyword ... 3-27 
Sample DDS to Show Record Format Problems ........... 3-47 
DDS Keyword Processing Order for Subfile Control ......... 4-10 
Vertically Displayed Subfile ........................ 4-16 
Horizontally Displayed Subfile ...................... 4-16 
Horizontally and Vertically Displayed Subfiles Displayed at the Same 

WIMCG® -.-"h kd ard. Bok & BGA Boe ee oe he oe ee od AS 4-17 
Sample DDS Using DSPMOD with Subfiles .............. 4-18 
Sample DDS Using SFLSIZ, SFLPAG, and ROLLUP Keywords .. 4-19 
Sample DDS for a Variable-Length Record .............. 4-20 
Sample DDS Using the SFLNXTCHG Keyword ............ 4-22 
Sample DDS for a Message Subfile ................... 4-23 
Sample DDS Using the DSPATR(PC) Keyword ............ 4-25 
Sample DDS Showing Customer Name Search Subfile ....... 4-32 
Window Title—Display Example ...................... 5-9 
DDS fora Window Title ................. 0.2.20 000. 5-10 
Radio Buttons and Check Boxes ..................-.. 6-1 
Example of aMenu Bar .................200 220005. 6-7 
DDS foraMenu Bar ........... 2.00.00 00 ee eee 6-9 


Menu Bar on a Graphical Display Station with Enhanced Interface . 6-10 
Menu Bar on a Nongraphical Display Station with Underline 


Gapabllityy (82 Gen nit LIU dete st Oe ee EG et lt ea Hy 6-10 

Menu Bar on a Nongraphical Display Station without Underline 

Capability: 2 4.207 eee ee ee ee ee ee ee Bae eo 6-10 

Menu Bar on a Display Station without Enhanced Interface ..... 6-10 

Selection Fields on a Graphical Display Station with Enhanced 

Interace: os Bk ke Sete BR ee We EP te oe BOS 6-11 

Selection Fields on a Nongraphical Display Station .......... 6-12 

DDS for Single-Choice and Multiple-Choice Selection Fields .... 6-13 
Xxi 


Xxii 


6-11. 
6-12. 


6-16. 


6-49. 
6-50. 
6-51. 
6-52. 


Example of DDS for Horizontal Selection Field ............ 
DDS for Suppressing Selection Indicators in a Selection Field 
Suppressed Selection Indicators in Selection Field .......... 
Example of a Pull-Down Menu ...................... 
DDS for a Pull-Down Menu ..................2..004. 
Pull-Down Menu on a Graphical Display Station with Enhanced 
INLEAGE ae Bp eh ee ag heat hee te es, ate es Sone 
Pull-Down Menu on a Nongraphical Display Station with Underline 
Capability s.'ic, Atte A aS 2 Cagehn, cohen ent ea Ore ie ttae! oe Gets 
Pull-Down Menu on a Nongraphical Display Station without 
Underline Capability .................0. 0... .00.. 
Pull-Down Menu on a Display without Enhanced Interface ..... 
DDS for Suppressing Selection Indicators in a Pull-Down Menu 
Suppressed Selection Indicators on Graphical Display Station 
Suppressed Selection Indicators on Nongraphical Display Station — . 
DDS for Accelerator Keys ..............0 220020005 
Accelerators ina Pull-Down Menu .................... 
DDS for Menu-Bar Switch Key and Cancel Key ............ 
Selection Lists on a Graphical Display Station with Enhanced 
Interface. Gass Sed. Boe ed eo we ee BE a OS GE 
Selection Lists on a Nongraphical Display Station with Underline 
Capability: £3 cia tee i Seek 8 oa peta ty od dotting tine te eee drag teeta gone sti rag 
DDS for Selection Lists—Example ................... 
DDS for Enabling Selection Indicators in a Selection List ...... 
Selection Indicators on Graphical Display Station ........... 
Scroll Bar on a Graphical Display Station with Enhanced Interface 
Scroll Bar on a Nongraphical Display Station with Underline 
Capability: ..hcs gnclacts wale 2 brea oe Ghee dante ee bans 
DDS for Scroll Bars—Example ..............-........ 
Push Buttons on a Graphical Display Station with Enhanced 
Interac’. sees ane Sad US bik Be ee ee a in 
Push Buttons on a Nongraphical Display Station with Underline 
Capability” 28% edieas be) ei eee a ee Ree Be EMA Gotte 
Push Buttons on a Nongraphical Display Station without Underline 
Gapabilit¥ g.c-Sitscte oka SA Gremahuntik SAS ie 6 Seale teh 
Push Buttons on a Display Station without Enhanced Interface 
DDS for Push Buttons—Example ...............-.... 
Control Values for the CHCCTL Keyword ............... 
DDS to Control the Availability of Choices ............... 
Single-Choice Selection Field with an Unavailable Choice ...... 
Examples of Valid DDS for Mnemonics ................. 
Examples of DDS Not Valid for Mnemonics .............. 
DDS Using CHCAVAIL and CHCSLT for Menu-Bar Choices 

DDS Using CHCAVAIL and CHCUNAVAIL for Selection Fields 

DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Selection 
FieldS:* 43. tne Ge heat ee ees BLS ee Pe ee BS 
DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Single 
Choice Selection List Choices  ...................... 
DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Multiple 
Choice Selection List Choices ...................... 
Continued-Entry Fields in Rectangular Arrangement ......... 
DDS Using MNUBARDSP on the Application Record ........ 
DDS Using MNUBARDSP on the Menu-Bar Record ......... 
DDS for Pull-Down Input (PULLINPUT) Parameter .......... 


Application Display Programming V4R1 


6-53. 
6-54. 
6-55. 
6-56. 
6-57. 
6-58. 
6-59. 
6-60. 
6-61. 
6-62. 
6-63. 
6-64. 
8-1. 
8-2. 
9-1. 
9-2. 
16-1. 
16-2. 
16-3. 
16-4. 
16-5. 
16-6. 
16-7. 
16-8. 
16-9. 
16-10. 
16-11. 
17-1. 
17-2. 
18-1. 
18-2. 
18-3. 
18-4. 
18-5. 
18-6. 
18-7. 
18-8. 
18-9. 
18-10. 
18-11. 


19-1. 
19-2. 
21-1. 
21-2. 
21-3. 
21-4. 
21-5. 
21-6. 
21-7. 
21-8. 
21-9. 
21-10. 
21-11. 


DDS for Return-Field Parameter ..........020.002.0.000.. 6-56 


DDS for Menu-Bar Choice Help ..................... 6-57 
DDS for Single-Selection Field Choice Help .............. 6-57 
A Help List fora Menu Bar ..................22.004. 6-59 
Help fora Named Field ...............2 0000050008 6-59 
Help fora Constant Field .....................0... 6-59 
Cursor Locations: sos.20ii eR bee Ge ee bin GAS 6-60 
Grid Line Structures ...........0.20. 0.00.20 0200004. 6-80 
DDS for Grid Line Structures—Example ................ 6-80 
DDS Coding Before Adding HTML Keyword .............. 6-85 
DDS Coding After Adding HTML Keyword ............... 6-86 
Graphic Image on an AS/400 5250 Gateway Display ......... 6-86 
Sample DDS Source for ERRSFL Keyword ............... 8-5 
Sample DDS Source for SFLMSGID Keyword .............. 8-6 
DDS Source for Sample Menu Called PERSMENU ........... 9-8 
DDS Source for Program Menu Example ............... 9-11 
An Example Menu ........... 00.000 eee 16-7 
Required UIM Tags fora Menu Panel ................. 16-8 
Example List Panel .................0. 00220048. 16-14 
Example of Alternate View of List ................... 16-14 
Required UIM Tags fora List Panel ..............2.... 16-17 
Example Confirmation List Panel ................... 16-27 
Example Data Presentation Panel ..............2.2.... 16-32 
Example Data Presentation Panel after Scrolling .......... 16-33 
Required UIM Tags for a Data Presentation Panel ......... 16-35 
Example Panel witha Menu Bar .................... 16-50 
Required UIM Tags fora Panel witha Menu Bar .......... 16-52 
Example of Job ExitFlag ...................2004. 17-25 
Example of Printout .................0 00022008. 17-35 
Sample H Specification in DDS Source ................. 18-4 
Sample DDS Source Showing HLPPNLGRP ............. 18-8 
Sample DDS Source Showing HLPPNLGRP and Option Indicators 18-9 
Sample DDS Source Showing HLPDOC  ............... 18-11 
Sample DDS Source Showing HLPDOC and Option Indicators .. 18-12 
Sample DDS Source Showing HLPRCD ............... 18-13 
Sample DDS Source Showing HLPRCD and Option Indicators .. 18-14 
Sample DDS Source with HLPRCD .................. 18-14 
Sample DDS Source to Show Secondary Help ........... 18-18 
Sample DDS Source to Show HLPCMDKEY ............ 18-21 
Sample DDS Source to Show HLPCMDKEY and Response 

INGICALOIS 2 oF ance DG ghey Ea Ae ae Ae a 18-22 
InfoSeeker Display ..................20 020020005 19-3 
Index Search Display ................20 020020005 19-4 
Sample Menu in QUSRTOOL ...................00. 21-4 
Sample Entry Display in QUSRTOOL .................. 21-5 
Sample Information Display (Two Pages) in QUSRTOOL ...... 21-6 
Sample List Display in QUSRTOOL ................... 21-7 
Sample Application Menu ...............2.2.200208. 21-9 
Sample Entry Display .....................2.02-. 21-11 
Sample Information Display (Two Pages) .............. 21-18 
Sample List Display ......................200-. 21-21 
Layout of Display with Location Information ............. 21-25 
Example of Processing Priority with List Display .......... 21-28 
Create User Profile Entry Display ................... 21-35 


Figures XXili 


21-12. 
21-18. 
21-14. 
21-15. 
21-16. 
21-17. 
21-18. 
21-19. 
21-20. 
21-21. 

A-1. 

D-1. 

G-1. 


Create Command Display with Additional Parameters Selected 
Second Display of Additional Parameters .............. 
Work with Members Using PDM Entry Display ........... 
Help Areas for Entry Displays ..................040. 
Help Areas for Information Displays .................. 
Help Areas for List Displays ...................000. 
Example of an Application Menu... 2... 2 
Entry Display: ..$25 4 v8 soe htoh 8 Retin ge Bee ee fete. 
Example of an Information Display .................. 
Example of aList Display ........................ 
Highlighting Classes Allowed in TEXT Area ............. 
IBM Host-System Code Scheme .................... 
Circumventing the Save Command ................... 


XXIV Application Display Programming V4R1 


Tables 


© Copyright IBM Corp. 1997 


Names Used in Steps for Creating Sample Displays .......... 1-1 
More Ways to Create Application Displays ................ 1-6 
More Ways to Create Online Help Information .............. 1-6 
Column positions forsample DDS ..................... 2-8 
DDS for Emphasizing Fields ....................... 2-21 
PRINT Keyword Results Using Print Key ................ 2-26 
Display Stations Implicitly Acquired When Display Files Are Opened = 3-2 
Information Available from the Get-Attributes Operation ........ 3-4 
Results of SLNO(*VAR) Values .............-..-22... 3-11 
Results from CLRL Example ...............-..-20.0.-. 3-16 
Keywords Ignored If Display Modes Are Changed .......... 3-28 
Display File Operations Supported by the Operating System and the 
Equivalent High-Level Language Commands ............. 3-49 
Optional Functions for Subfiles ....................240. 4-4 
Subfile Operations Supported by the System and Equivalent HLL 
Commands: ©... 840 eer a eae eae oo ae ae ee AS 4-15 
Functions Supported by Hardware Configurations A,B,andC .... 6-2 
Functions Supported by Hardware Configurations D,E, andF .... 6-3 
How a Scroll Baris Sized ..........22...2......00.. 6-32 
Scroll Bar Operation ...........2.. 0.00.20 0200008. 6-33 
Keywords Used to Define Colors and Display Attributes ....... 6-39 
Values Returned in MNUCHOICE and PULLINPUT ......... 6-55 
Actions Performed at Different Cursor Locations ........... 6-61 
File Redirections ........... 0... 00020 eee eee 7-7 
File Redirection Combinations ....................-.. 7-7 
System Message Number Ranges .................-.. 8-10 
Major Return Code Definitions ...................0.4. 8-11 
Restrictions for Display File Menus .................... 9-4 
Suggestions for Display File Menus .................... 9-5 
Display File and ICF File Entry Field Attributes ............ 12-1 
CHIRID: Values) ..¢. 250% Gos Goals tune weeks be le Ghal Pe edd & 13-5 
Initial Values of Dialog Variable .................0... 17-2 
UIM CCSID/CHRID Conversions for Display .............. 17-5 
UIM CCSID/CHRID Conversions for Print ............... 17-7 
Cursor-Sensitive Function Keys Assigned to Dialog Commands . 17-29 
Different Ways to Define Online Help Information ........... 18-2 
Characteristics of Different Methods of Online Help Information .. 18-2 
Help for Sample Display .....................00.. 18-5 
Other DDS Keywords for UIM Help ................... 18-6 
Help for Sample Display Using Panel Groups ............. 18-7 
Help for Sample Display Using HLPDOC ............... 18-10 
Help for Sample Display Using HLPRCD ............... 18-13 
Source Members for Displays Example in QUSRTOOL (Install, 
Create, and Delete) ............. 0.000000 02. 2 eee 21-2 
Source Members for Displays Example in QUSRTOOL (Sample 
Displays, Command, and Online Help Information) .......... 21-3 
Objects Created When Creating Example Objects .......... 21-4 
Required Functions and Attributes of All AS/400-Style Displays .. 21-8 
Optional Functions and Attributes of All AS/400-Style Displays ... 21-8 
Function Key Assignments ................+22008. 21-38 
XXV 


Xxvi 


A-31. 
A-32. 
A-33. 
A-34. 
A-35. 
A-36. 
A-37. 
B-1. 
B-2. 
C-1. 
C-2. 
C-3. 
C-4. 
C-5. 
D-1. 


Type of Help for Each Help Area—Menu Display .......... 
DDS Considerations—-Help on Menu Displays ............ 
Type of Help for Each Help Area—Entry Display ........... 
DDS Considerations—Help on Entry Displays ............ 
Type of Help for Each Help Area—Information Display ....... 
DDS Considerations—Help on Information Displays ......... 
Type of Help for Each Help Area-List Display ............ 
DDS Considerations—Help on List Displays ............. 
CUA Entry Dialog Actions ...........2...........-. 
Tag Attributes That Can Be Continued ................. 
Restrictions Associated With Mixed Panels .............. 
Tags Allowed Between the CLASS and ECLASS Tag ........ 
Attribute Summary for Each BASETYPE ................ 
Tags Allowed Between the DATA and EDATA Tags ......... 
Tag Allowed Between the DATASLT and EDATASLT Tags ..... 
Tags Allowed Between the DL and EDL Tags ............. 
Tag Allowed Between the KEYL and EKEYL Tags .......... 
Tags Allowed Between the LIST and ELIST Tags .......... 
NOCMD and NOEXT Attribute Interaction ............... 
Emphasis Values ........... 00.000 eee ee 
Layout Values for Width=80 ...... 2... 2... 0... .0004 
Layout Values for WIDTH=182 .........2.2.22.2....... 
Layout Values for WIDTH=1382 ........2.2.22.222.2..... 
Tag Allowed Between the MBAR and EMBAR Tags ........ 
Tags Allowed Between the MBARC and EMBARC Tags ...... 
Tags Allowed Between the MENU and EMENU Tags ....... 
Tag Allowed Between the MENUGRP and EMENUGRP Tags _ .. 
Tags Allowed Between the NOTE and ENOTE Tags ........ 
Tags Allowed Between the OL and EOL Tags ............ 
Tags Allowed Between the PANEL and EPANEL Tag ....... 
Layout of UIM finger print ....................000. 
Tags Allowed Between the PARML and EPARML Tags ...... 
Tags Allowed Between the PDFLD and EPDFLD Tags ...... 
Valid Action Text for ACTION Values ................. 
Tags Allowed Between the PNLGRP and EPNLGRP Tags 

Tags Allowed Between the PRTHEAD and EPRTHEAD Tags_.. . 
First Line of Heading with Print Width 132 .............. 
First Line of Heading with Print Width 80 ............... 
Second Line of Heading with Print Width 132 ............ 
Second Line of Heading with Print Width 80 ............. 
Tags Allowed Between the PRTPNL and EPRTPNL Tags ..... 
Tags Allowed Between the SLandESL Tags ............ 
Tag Allowed Between the TLandETL Tags ............. 
Tag Allowed Between the TT and ETT Tags ............. 
Tags Allowed Between the UL and EUL Tags ............ 
Attributes of UIM-Defined Variables (Z-Variables) .......... 
Summary of the Valid Uses of Dialog Commands .......... 
Summary of the Effects of Dialog Commands ............. 
Open Feedback Area... 1... 2. 2 
Device Definition List ...................20.200.. 
Common I/O Feedback Area .............-..-02005. 
I/O Feedback Area for Display Files ................... 
Get Attributes: 2.5 sche yg Bk ea ee SI ea we te SE DE 
IBM Japanese Character Set ...................004. 


Application Display Programming V4R1 


IBM Korean Character Set ............... 0.222004. D-2 
IBM Simplified Chinese Character Set ................. D-2 
IBM Traditional Chinese Character Set ................. D-3 
Summary Chart for OS/400 Edit Codes .................. F-1 
Valid Edit Codes, Source Data, and Edited Output ........... F-3 
IBM-Supplied Edit Descriptions ....................0.. F-4 
Message Files for MSGID ....................0... G-5 
Message Files for MSGID ................-...0... G-5 


Tables XXVii 


XXViii Application Display Programming V4R1 


Notices 


References in this publication to IBM products, programs, or services do not imply that IBM intends to 
make these available in all countries in which IBM operates. Any reference to an IBM product, program, 
or service is not intended to state or imply that only that IBM product, program, or service may be used. 
Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent 
product, program, or service may be used instead of the IBM product, program, or service. The evaluation 
and verification of operation in conjunction with other products, except those expressly designated by IBM, 
are the responsibility of the user. 


IBM may have patents or pending patent applications covering subject matter in this document. The fur- 
nishing of this document does not give you any license to these patents. You can send license inquiries, 
in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY 
10594, U.S.A. 


Licensees of this program who wish to have information about it for the purpose of enabling: (i) the 
exchange of information between independently created programs and other programs (including this one) 
and (ii) the mutual use of the information which has been exchanged, should contact the software interop- 
erability coordinator. Such information may be available, subject to appropriate terms and conditions, 
including in some cases, payment of a fee. 


Address your questions to: 


IBM Corporation 

Software Interoperability Coordinator 
3605 Highway 52 N 

Rochester, MN 55901-7829 USA 


This publication could contain technical inaccuracies or typographical errors. 


This publication may refer to products that are announced but not currently available in your country. This 
publication may also refer to products that have not been announced in your country. IBM makes no 
commitment to make available any unannounced products referred to herein. The final decision to 
announce any product is based on IBM's business and technical judgment. 


This publication contains examples of data and reports used in daily business operations. To illustrate 
them as completely as possible, the examples include the names of individuals, companies, brands, and 
products. All of these names are fictitious and any similarity to the names and addresses used by an 
actual business enterprise is entirely coincidental. 


This publication contains small programs that are furnished by IBM as simple examples to provide an 
illustration. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot 
guarantee or imply reliability, serviceability, or function of these programs. All programs contained herein 
are provided to you "AS IS". THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED. 
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Programming Interface Information 


This publication is intended to help the application programmer create and maintain displays for an appli- 
cation. This publication documents Product-Sensitive Programming Interface and Associated Guidance 
Information provided by the OS/400 licensed program. 


Product-Sensitive programming interfaces allow the customer installation to perform tasks such as diag- 
nosing, modifying, monitoring, repairing, tailoring, or tuning of this IBM software product. Use of such inter- 
faces creates dependencies on the detailed design or implementation of the IBM software product. 
Product-Sensitive programming interfaces should be used only for these specialized purposes. Because 
of their dependencies on detailed design and implementation, it is to be expected that programs written to 
such interfaces may need to be changed in order to run with new product releases or versions, or as a 
result of service. 


Trademarks 


The following terms are trademarks of the IBM Corporation in the United States or other countries or both: 


AFP Operating System/400 
AIX OS/2 

Application System/Entry OS/400 

APPN PS/1 

AS/400 PS/2 

Common User Access RPG 

CUA SAA 

IBM System/36 
Information Assistant System/38 
InfoWindow System/370 
Integrated Language Environment Systems Application Architecture 
OfficeVision 400 


Microsoft, Windows, and the Windows 95 logo are trademarks or registered trademarks of Microsoft Cor- 
poration. 


PC Direct is a trademark of Ziff Communications Company and is used by IBM Corporation under license. 


UNIX is a registered trademark in the United States and other countries licensed exclusively through 
X/Open Company Limited. 


C-bus is a trademark of Corollary, Inc. 
Java and HotJava are trademarks of Sun Microsystems, Inc. 


Other company, product, and service names, which may be denoted by a double asterisk (**), may be 
trademarks or service marks of others. 
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About Application Display Programming (SC41-5715) 


This book contains information on: 


e Using DDS to create and maintain displays for an application 
¢ Creating and working with display files on the system 

¢ Creating online help information 

e Using UIM to define panels and dialogs for an application 


Use this book to program for application and help displays. 


This book does not describe all the DDS keywords or the configuration of display 
stations. You may need to refer to other IBM books for more specific information 
about a particular topic. 


For a list of related publications, see the “Bibliography.” 


Who Should Use This Book 


This book should be used by application programmers who create or work with 
application and help displays. You should also have knowledge of the source entry 
utility (SEU) and data description specifications (DDS). 


This book assumes that a device description already exists to describe your display 
station to the system. 


Prerequisite and Related Information 


For information about other AS/400 publications (except Advanced 36), see either 
of the following: 


¢ The Publications Reference book, SC41-5003, in the AS/400 Softcopy Library. 

¢ The AS/400 Information Directory, a unique, multimedia interface to a 
searchable database that contains descriptions of titles available from IBM or 
from selected other publishers. The AS/400 Information Directory is shipped 
with the OS/400 operating system at no charge. 


Information Available on the World Wide Web 


More AS/400 information is available on the World Wide Web. You can access this 
information from the AS/400 home page, which is at the following uniform resource 
locator (URL) address: 


http: //www.as400.ibm.com 


Select the Information Desk, and you will be able to access a variety of AS/400 
information topics from that page. 
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Summary of Changes to Application Display Programming 


HTML Keyword 

You can use HTML tags to update applications for use on the Internet through the 
World Wide Web. For more information, see“DDS Keywords” on page 6-5 and 
“Inserting HTML Tags” on page 6-82. 


Changes or additions to the text are indicated by a vertical line (|) to the left of the 
change or addition. 


The following programming languages are no longer offered as licensed programs 
in V3R7: 


AS/400 BASIC, FORTRAN/400, AS/400 PL/I, AS/400 Pascal, and RM/COBOL-85 
for the AS/400 


Therefore, references to these products have been removed or adjusted in this 
edition. 
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Part 1. Building a Sample Display with Online Help 
Information 
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Chapter 1. Building a Sample Display with Online Help 
Information 


This chapter outlines the steps you need to do to create a sample display with 
online help information on the AS/400. If you are not sure how to do one or more 
of the steps, see the additional information referred to in each step. 


The Application Display: The sample display is created using a display file (also 
known as a display device file). A display file is an object, or named storage 
space, created by the user that contains the file description. The file description 
identifies the display station used and, optionally, the record formats used by the 
display station. Record formats describe the characteristics and arrangement of 
the fields on a display. Record formats are defined using data description spec- 
ifications (DDS), which describe data attributes outside the application program 
that processes the data. 


The Online Help Information: The online help information for the sample display 
is defined using help panel groups. A panel group is an object, or named storage 
space, that contains text to be used as online help information by the user interface 
manager. The user interface manager (UIM) is a function of the operating system 
that provides online help information for displays, including help for part or all of a 
display, help for commands, the InfoSeeker function, the index search function 
(selectable help topics), and hypertext (the capability to link different units of online 
help information). 


The following table lists the sample names used in the steps: 


Table 1-1. Names Used in Steps for Creating Sample Displays 


Name What It Is 

SRCSAM Sample source file 

ADMSAM Sample source member for application display 

DSPSAM Sample display file 

HDMSAM Sample source member for help display 

PNLSAM Sample panel group 

LIBSAM Sample library that contains source file SRCSAM, display file 


DSPSAM, and panel group PNLSAM 


The steps show only one way to create a sample display with online help informa- 
tion. Other methods are discussed at the end of this chapter. 


1. Create the source file SRCSAM using the Create Source Physical File 
(CRTSRCPF) command; create the library LIBSAM using the Create Library 
(CRTLIB) command. 


2. Enter the Start Programming Development Manager (STRPDM) command to 
begin using the programming development manager (PDM). When the display 
appears, select option 3 (Work with members). 
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AS/400 Programming Development Manager (PDM) 
Select one of the following: 
1. Work with libraries 
2. Work with objects 
3. Work with members 


9. Work with user-defined options 


Selection or command 
===> 3 


F3=Exit F4=Prompt F9=Retrieve F10=Command entry 
F12=Cancel F18=Change defaults 
(C) COPYRIGHT IBM CORP. 1981, 1993. 


— — 


-— Additional Information 


The programming development manager (PDM) is the part of the 
AS/400* Application Development Tools licensed program that allows users 
to perform several operations (such as copy, delete, and rename) from lists 
of libraries, objects, and members. 


Since the display file (which will be created in step 9) does not actually 
contain any data, the DDS source for a display file is entered in a source 
file. A source file is an object that is made up of one or more source 
members, which are the different sets of data that make up your DDS 
source. 


More information about the programming development manager is available 
in the ADTS/400: Programming Development Manager book. 


3. When the Specify Members to Work With display appears, complete the file 
and library information and press the Enter key. 


— 


Specify Members to Work With 


Type choices, press Enter. 


FRE. oe te: Se cat eee? Bw SRCSAM Name 
ETDRARYs a: P88 Be as LIBSAM *LIBL, *CURLIB, name 
Member 
Name - 2 4 6 @ Glee Bes *ALL *ALL, name, *generic* 
Type ..... eee *ALL *ALL, *BLANK, type, *generic* 


F3=Exit F5=Refresh F12=Cancel 
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4. The Work with Members Using PDM display appears. 


(— > 


Work with Members Using PDM 


FUTG: ce bya SRCSAM 
Library .... LIBSAM Position to ..... 
Type options, press Enter. 
2=Edit 3=Copy 4=Delete 5=Display 6=Print 
7=Rename 8=Display description 9=Save 13=Change text 
Opt Member Type Text 


(No members match the subsetting criteria) 


Parameters or command 

===> 

F3=Exit F4=Prompt F5=Refresh F6=Create 
F9=Retrieve F10=Command entry F23=More options F24=More keys 


Press F6 on this display to create a new member. 


5. The Start Source Entry Utility display appears. Complete the information on 
this display and press the Enter key. 


(- a 


Start Source Entry Utility (STRSEU) 


Type choices, press Enter. 


Source Til@ 6 6 2-6, 6% 8 wos > SRCSAM Name, *PRV 

Library. .&. ac. le eo ea a > LIBSAM Name, *LIBL, *CURLIB, *PRV 
Source member ......... ADMSAM Name, *PRV, *SELECT 
Source type .......... DSPF Name, *SAME, BAS, BASP, C... 
Text 'description’....... DDS for sample display 


Bottom 
F3=Exit F4=Prompt F5=Refresh  F12=Cancel F13=How to use this display 
F24=More keys 


— — 


-—— Additional Information 


The source entry utility (SEU) is a function of the Application Development 
ToolSet licensed program that is used to create and change source 
members. More information about the source entry utility is available in the 
ADTS/400: Source Entry Utility book. 


6. Because you are creating a new member, the SEU Edit display appears with a 
screen of blank lines. The text on the last line of the display, Member 
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ADMSAM added to file SRCSAM indicates that SEU added the new member to 
the file you specified. 


i ==) 
Columns ....: 1 71 Edit LIBSAM/SRCSAM 
SEU==> ADMSAM 
FMT DP ..... AANO1NO2ZNO3T .Name++++++RLent++TDpBLinPosFunctions+t+t+++t+++t+++4++++4+ 


odode Beginning Of data sake dik iid ERI RK HI RK 


KARKKKEKKEERKAKKEKEREKR EN OF data keKKKKAKAKKHKKKAK KERR RR KKK RRR R RR RERE RRR EK 


F3=Exit F4=Prompt F5=Refresh 
F10=Top F11=Bottom F24=More keys 
Member ADMSAM added to file LIBSAM/SRCSAM. 

+ 


— — 


7. On the SEU edit display, enter the DDS source statements for the new 
member. Since the instructions in this chapter allow you to provide online help 
information for the sample display, make sure your DDS source includes the 
necessary DDS keywords to enable and access help. 


-— Additional Information 


SEU has many functions available to help you enter your DDS. More infor- 
mation about the functions of SEU is available in the the ADTS/400: Source 
Entry Utility book. 


For information about describing your display using DDS, see “Defining 
Display Fields and Functions in a Record Format” on page 2-7 in this 
guide. For more information about the DDS keywords needed for online 
help information, see Chapter 18, “Making Online Help Information Acces- 
sible for Your Display File.” 


8. When you are finished entering your DDS source, press F3 and complete the 
information on the Exit display. Press the Enter key. 


9. To create the new display file, enter the Create Display File (CRTDSPF) 
command on any command line. Make sure you specify the source file and 
member that contains your DDS source: 


CRTDSPF FILE(LIBSAM/DSPSAM) SRCFILE(LIBSAM/SRCSAM) SRCMBR(ADMSAM) 
Press the Enter key. 


-— Additional Information 


For more information about creating display files, see “Creating a Display 
File and Description” on page 2-4. 


10. To add online help information to the sample display, create a second source 
file member for the UIM source. You are not required to create the second 
source member in the same source file that you created your DDS source in; 
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however, do not use the same source member for both the DDS and UIM 
source. 


To create the second source file member, repeat steps 2 through 4. When the 
Start Source Entry Utility display appears again, continue with step 11. 


11. Complete the information on the Start Source Entry Utility display by specifying 


the following: 

For this prompt... Enter this... 

Source member HDMSAM 

Source type PNLGRP 

Text description UIM help for sample display 


12. On the SEU edit display, enter the UIM source statements for the new member. 


-— Additional Information 


For information about defining your online help information using UIM, see 
“Defining Online Help Information in a Panel Group” on page 20-1. 


13. When you are finished entering your UIM source, press F3 and complete the 
information on the Exit display. Press the Enter key. 


14. Enter the Create Panel Group (CRTPNLGRP) command on any command line: 
CRTPNLGRP PNLGRP(LIBSAM/PNLSAM) SRCFILE(LIBSAM/SRCSAM) SRCMBR(HDMSAM) 
Press the Enter key. 


-— Additional Information 


For more information about panel groups, see “Creating and Deleting Panel 
Groups” on page 20-15. 


Although one library was used in the previous steps, you are not required to create 
the different objects for your displays in the same library. 


Other ways of creating your own application displays on the AS/400 system follow: 
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Table 1-2. More Ways to Create Application Displays 


Method 


Description 


Where to Find More 
Information 


Screen design aid 
(SDA) 


A function of the Application Development ToolSet licensed 
program that helps you design, create, and maintain displays 
and menus. SDA allows you to design your displays as you 
want them to look and then the system creates the DDS 
source and a display file for you. 


ADTS/400: Screen 
Design Aid book. 


QUSRTOOL 


A library, which is optionally installable on your system, that 
provides you access to examples of various tools and pro- 
gramming techniques that may help you with application 
development and management of your system. The display 
example in QUSRTOOL provides four sample displays with 
online help information. You can copy the source for these 
displays into a library of your choosing and then tailor them 
for your own use. 


“Using the Displays 
Example in the 
QUSRTOOL Library” on 
page 21-1 


UIM panel groups 


A part of the system that allows you to define panels and 
dialogs for your application. The UIM controls the panel's 
appearance and assures consistency with panels developed 
by IBM *. 


Chapter 16, “Introduction 
to the User Interface 
Manager” on page 16-1 


Other ways of creating online help information for your displays follow: 


Table 1-3. More Ways to Create Online Help Information 


Method 


Description 


Where to Find More Information 


Help documents 


Objects for online help information that are 
created using AS/400 OfficeVision, which 
is the IBM licensed program that provides 
many office functions, such as word pro- 
cessing. This can be accessed from 
display files and not the UIM application 
panels. 


“Defining Online Information in a Document” 
on page 20-18 and “Specifying Documents 
in Your Display File” on page 18-9 


Help records 


DDS keywords that allow you to create 
your online help information in the same or 
a different member as the DDS source for 
your application display. This can be 
accessed from display files and not the 
UIM application panels. 


“Defining Online Help Information in a DDS 
Record” on page 20-19 and “Specifying 
Records in Your Display File” on page 18-12 


To compare and contrast the different ways to create online help information, see 
“Choosing between Panel Groups, Documents, and Records for Help” on 


page 18-2. 
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Part 2. Programming Application Displays Using Display 


Files 
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Chapter 2. Defining Your Display in a Display File 


A display file defines the format of the information to be presented on a display 
station, and how that information is processed by the system on its way to and from 
the display station. Data description specifications (DDS) describe the data 
referred to by a display file. 


This chapter tells you about display files, including how to create them and how to 
provide DDS source for them to describe your display. 


Establishing a Display File 


A display file is an object on the system. An object is a named storage space that 
consists of a set of characteristics that describe itself and, in the case of a display 
file, the data. Like other objects on the system, display files have the following char- 
acteristics: 


¢ A display file is named and placed in a library when it is created. The file name 
and library name allow you to refer to the display file in your applications. 


¢ Once a display file is created, it can be changed, secured, saved, restored, or 
deleted. 


Before an application program can work with a display station, a display file must 
be opened to allow data to flow between the program and the display station. 


Application Display 
Program File 


Data 


Device 
Description 
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A device description, which is a system object that describes the display station to 
the system, must also exist for the display station. A device description contains 
information such as device address, device type, model number, and features. 
Device descriptions are usually created by system personnel or, for locally attached 
devices, can be created during the automatic configuration of the system. 


A program may work with more than one display station at a time by doing one of 
the following: 


¢ Opening more than one display file 
¢ Opening a display file that allows more than one display station to be attached 
to an open file 
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Since a display file does not have a set of data uniquely associated with it, the 
relationship between the data and the display file is established when the display 
file is opened and ends when the display file is closed. 


Determining File Descriptions 


The file description, which is created at the same time the display file is created, 
describes the characteristics of the display file and determines how the display file 
does the following: 


¢ Controls the display station 
e¢ Formats output data from the program for presentation at the display station 
e¢ Formats input data from the display station for presentation to the program 


A file description determines how a program is able to use the file. If a program 
attempts to perform an operation that is inconsistent with the display file 
description, the system does not allow the operation. 


The file description is created and deleted at the same time as the display file it 
describes. Some parts of a file description may be changed, either permanently 
with the Change Display File (CHGDSPF) command or temporarily with the Over- 
ride with Display File (OVRDSPF) command. 


A file description describes data at three different levels: 


e Field level 
e Record level 
e File level 


The following sections describe these levels. 


Field-Level Descriptions 

A field is the smallest unit of data that is recognized and handled by the data man- 
agement support of the system. A field-level description allows you to give the 
system detailed characteristics of a field, such as: 


e Where on the screen the field is to appear 

e¢ What type of data is valid for the field 

e Whether the field should be highlighted in some way 

¢ How it will be presented from the program to the system on output and from 
the system to the program on input. 

e Where each field is relative to the start of a record 

e What the characteristics of each field will be while in the system 

e Where the data for each field should be acquired from for output 

e Where and how input from the display station should be placed so the program 
can use it 

e Whether the field is an input-capable field or output-capable field only 


Only field-level descriptions can determine that valid data is specified for individual 
fields on a display. 
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Record-Level Descriptions 

A record is an ordered set of one or more fields. A record-level description 
allows you to tell the system what a particular record looks like, or its record 
format. 


A record-level description is given in one of two ways: 


e If field-level descriptions are also used, you identify what fields make up the 
record format and the order of these fields within the record format. The 
system can then perform separate operations on each field described with a 
field-level description in the record-level description. For example, one field can 
be highlighted while another is not. 


e If field-level descriptions are not used, the record format is given by specifying 
the length of the record. The system handles the entire record as a unit and 
cannot perform operations on one part of the record one way and another part 
a different way. 


Since records are used to transfer data between the system and the application 
program, a record-level description is required for display files. 


File-Level Descriptions 

A file is an organized set of zero or more records (a file with zero records is 
empty). A file-level description is a description that applies to the file as a whole. 
For a display file, you can specify the following in the file-level description: 


e What record formats are valid for the display file 

e What display station should be usable with the display file 

e¢ What graphic character set is to be assumed for the data that will be entered 
through the display file 


Deciding Whether to Describe Data Inside or Outside Your Program 


When the detailed description of the display file and the data it refers to is con- 
tained in a display file rather than imbedded in a program, the data is called 
externally described data. When the data is described within the source program, 
the data is called program described data. 


Externally Described Data 

Externally described data exists independently of any program that uses the file. 
Using externally described data, you can produce a detailed and standard 
description of both the display file and any data that can be processed through the 
display file. 


To use externally described data, you need to declare that the display file is to be 
used as an externally described file. The language compiler or interpreter extracts 
the file description from the display and then incorporates it into the program. 


There are several advantages to using externally described data: 


e Increased programmer productivity. The language automatically describes the 
record layouts for you without additional coding. You need to describe records 
and fields only once (when the file is created). You can then refer to these 
fields within the program. 


Chapter 2. Defining Your Display in a Display File 2-3 


e Ease of file and program maintenance. When fields are added, deleted, or 
changed, it can be done in one place instead of maintaining the record layout 
in each program that uses the file. 


e Increased data integrity. Since the fields and records are described in one 
central location, there is less chance of programming errors when describing 
the data in the file to the program. All application programs using the file will 
have the same view of the data. Moreover, the system view of the data 
becomes the same as the application program view. 


e Level checking provided. Level checking is an automatic method used when 
the program is run that determines if the file description has changed since the 
program was last compiled. Depending on the type of change, the program 
may only need to be recompiled without modification. This allows better control 
over program maintenance. There is more information on the level-checking 
function in “Detecting File Description Changes” on page 2-6. 


Program-Described Data 

You are not required to use external descriptions to describe your displays in your 
program. If you do not use externally described data, you must declare variables in 
your source program that define to the compiler or interpreter what the data looks 
like. 


When program-described data is used, the program and the system may not have 
the same view of the data: 


e If the file does not have any field-level descriptions, the system must operate at 
the record level. The only concern in this case is that the record length the 
program is using is the same as what the system is using. It need not be, but 
the system always operates with the record length it has. If the record length 
that the system is using differs from the record length the program is using, the 
system truncates or pads as necessary. 


e If the file has field-level descriptions but the program does not use them, the 
system uses the field-level descriptions even though the program does not. 
The system expects the program to present data according to the file 
description and, conversely, provides data to the program according to the 
description. 


More information about program-described data is found in “Using Program- 
Described Data” on page 2-27. 


Creating a Display File and Description 
Display files are created using the Create Display File (CRTDSPF) command. 


You can define the DDS for your display file in one of two ways: 


e Using the screen design aid (SDA) utility 
e Entering your own DDS source 


You can specify certain attributes about your display file. Information about these 
attributes is found in the following: 


¢ “Deferring the Write Operation Until a Read Request is Made” on page 3-26 
e “Saving Previously Displayed Information” on page 3-43 

¢ CL Reference 

¢ Security — Reference 
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The following illustration compares the two ways to create display files: 


Two Ways to Define Display Files 


Enter your own DDS and then use the 
Create Display File (CRTDSPF) Command ... 
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2'Selection! 
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CRTDSPF command compiles DDS and creates 
display file object. 


Go To Another List 


Select one of the following: 


. Work with documents in folder 

. Work with documents to be printed 
- Work with folders 

Work with nontext document data 
. Work with text profiles 
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Design your display as it will look 
using the screen design aid (SDA) utility ... 
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SDA generates DDS and runs the CRTDSPF command. 
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You may also combine the two methods, creating an initial display using SDA and 


then tailoring the generated DDS. 


Changing the File Description 


After a display file has been created, the file description can be changed: 


¢ To change the file description that was originally specified on the CRTDSPF 
command, use the Change Display File (CHGDSPF) command. 


e To change the file-level, record-level, or field-level information contained in the 
DDS source, you must first update the DDS source and then create the display 
file again using the CRTDSPF command. A new display file can be created 
without deleting the existing display file by specifying REPLACE(YES) on the 


CRTDSPF command. 


¢ To change both the CL command file-level descriptions and the DDS source, 
specify the new values when you create the display file again. 
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Changes to display file descriptions are applied according to the following: 


e If the file-level description was changed with a CL command, any program that 
uses the file will automatically use those new descriptions. 


e lf the DDS descriptions were changed and the program uses the file as a 
program-described file, the system uses the new file-level description. 
However, if the DDS descriptions were changed and the program uses the file 
as an externally described file, then the record-level and field-level descriptions 
used when the program was compiled may not match the changed file. If the 
system detects a mismatch when the program opens the file, an error occurs. 
See “Detecting File Description Changes.” 


You may also temporarily change a file-level description when a display file is 
opened. More information about these temporary changes is found in Chapter 7, 
“Overriding Display Files and Display File Attributes” on page 7-1. 


Detecting File Description Changes 


When a program that uses externally described files is compiled, the high-level lan- 
guage compiler extracts the record-level and field-level descriptions for the files 
referred to in the program and makes those descriptions part of the compiled 
program. When you run the program, you can verify that the descriptions with 
which the program was compiled are the current descriptions. 


The system assigns a unique level identifier for each record format when the file it 
is associated with is created. The system uses the following information to deter- 
mine the level identifier: 


e¢ Record format name 

e Field name 

¢ Total length of the record format 

¢ Number of fields in the record format 

e Field attributes (for example, length and decimal positions) 
¢ Order of the fields in the record format 


Display files may also use the number of and order of special fields called indica- 
tors to determine the level identifier. 


If you change the DDS for a record format and change any of the items in the 
preceding list, the level identifier changes. 


To check for changes in the level identifiers when you run your program, specify 
“YES for the LVLCHK parameter on the CRTDSPF or CHGDSPF command. When 
the display file is opened, the level identifiers of the display file and the file 
description that is part of the compiled program are compared format-by-format. If 
the identifiers differ or if any of the formats specified in the program do not exist in 
the file, a message is sent to the program to identify the condition. 


If the identifiers differ, either the formats have been changed or your program does 
not use the changed formats. If the changed format does affect your program, you 
may decide to do the following: 


¢ Compile the program again so that the changes are included 
¢ Determine if the changes affect your program before deciding what action to 
take. 
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To check the changes to the record format, run one of the following commands: 


¢ Display File Field Description (DSPFFD) command to display the record-level 
and field-level descriptions 


e Start Source Entry Utility (STRSEU) command to display the source file con- 
taining the DDS for the file 


¢ Display File Description (DSPFD) or the DSPFFD command to display the 
format level identifier defined in the file 


¢ Display Program References (DSPPGMREF) command to display the format 
level identifier that was used when the program was created 


Defining Display Fields and Functions in a Record Format 


A record format in a display file describes both the format of the record as it is used 
in the application program and the format of the record when it is displayed (see 
Figure 2-2 on page 2-8). 


A record format contains field descriptions, which are defined using data description 
specifications (DDS). For each field in a record format, you describe the following: 


¢ Location of the field on the display 

e Length of the field 

¢ Type of data contained in the field (character, zoned decimal, or floating point) 
e Field type (output, input, or output/input). 


;—— Information about DDS keywords 


This section describes how DDS keywords are used to describe the information 
on your display. For more information about specific DDS keywords, see the 
DDS Reference. 


DDS for Display File: The following source shows the DDS for a sample display 
file: 


| saath eepe Laeipe Pac Gee ot ale ccpe Se we ease OS oes lS saints wav On aston cg Thee 


A R RECORD 

A 3 2'Customer Number: ' 
A CUST 5 0 3 20 

A 3 27'Customer Name: ' 

A NAME 20 3 44 

A 4 27'Address:' 

A ADDR 20 4 44 

A CITY 20 5 44 

A STATE 2 5 66 

A ZIP 5 0 570 


Figure 2-1. Sample DDS Source for a Display File 


Table 2-1 on page 2-8 shows the column positions and descriptions for the DDS 
specifications. 
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Table 2-1. Column positions for sample DDS 


Column Definition Starting Position 
17 Type of name 17 
19 - 28 Field name 19 
30 - 34 Length 34 
36 - 37 Decimal positions 37 
39 - 41 Line location 41 
42 - 44 Position location 44 
45 - 80 Function 45 


Record Format Used by the Program: The program passes the fields in the 
record in the same order that you described them in the DDS source. 


CUST NAME ADDR CITY STATE ZIP 


14 516 251 26 45146 65166 67168 72! 
| | | | 
| | | | | | | 


RV2W028-1 


Record Format on the Display: The fields are displayed according to the display 
positions you assigned them in the DDS source. 


CUST NAME 
| f 


: 


Customer Number. 41394 CustomerName: Sorenson and Walton 


Address: 500 5th Avenue 
New York NY 55555 
ADDR CITY STATE ZIP 


RSLH714-0 


Figure 2-2. Record Formats in the Program and on the Display 


Understanding the Field Attribute Characters 


Each field displayed has a beginning attribute character and an ending attribute 
character associated with it that define the displayed field. The beginning char- 
acter precedes the first character of a field and is displayed as a blank. The ending 
attribute character follows the last character of a field and is also displayed as a 
blank. For example, if you specify a field for positions 2 through 8, the beginning 
attribute character is in position 1 and the ending attribute character is in position 9. 
These characters are not included in the field length you specify in DDS. A begin- 
ning attribute character can overlap an ending attribute character; that is, they can 
occupy the same position on the display. However, nothing else can overlap the 
beginning attribute character. Therefore, when you design a display, you must 
allow one space for the beginning attribute character of each field. You can use 
the blank attribute character to space between fields when they are displayed. 
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If field-level descriptions are not used, the entire record is treated as a field with a 
beginning attribute character and an ending attribute character. 


When a record is displayed so that the last field in the record ends in the last posi- 
tion on the line, the ending attribute character for that field is in the first position of 
the next line. The beginning attribute character of the first field in the next record 
can be superimposed on the ending attribute character. For example, if the ending 
attribute character for the last field in record 1 is in position 1 of line 5, the begin- 
ning attribute character for record 2 can also be in position 1 of line 5. In this case, 
the first record is not considered to be overlapped. However, if the first field in a 
record begins in position 1, which means that the beginning attribute character is in 
the last position of the preceding line, the previous record is overlapped and is 
cleared from the display. 


To see the locations of fields in the input records and output records used by the 
program, see the printed DDS output produced when you created your display file 
using the CRTDSPF command. 


Understanding How Record Format Fields Can Be Used 
The fields you describe in the record format can be used in the following ways: 


Note: To see the location of positions on a DDS form, see Table 2-1 on 
page 2-8. 


e Input fields are fields that are passed from the display station to the program 
when the program reads a record. Input fields can be initialized with a default 
value (specified in the record format for the display file). If the user does not 
change the field and the field is selected for input, the default value is passed 
to the program. Input fields that are not initialized are displayed as blanks into 
which the user can enter data. By default, input fields are underlined on the 
display. 


Note: Trailing blanks on input fields are replaced by null and not blank charac- 
ters; therefore, the Insert key can be used to insert characters in all 
input fields that end in blanks. 


¢ Output fields are fields that are passed from the program to the display station 
when the program writes a record to a display. Output fields contain data pro- 
vided by the program, not by the user. To specify an initial value for a named 
output field, see “Specifying Default Values for Fields” on page 3-26. 


In the case of subfiles, which are special records used to display lists of infor- 
mation, output fields are returned to the program as if they were output/input 
fields. 


¢ Output/input fields are fields that are passed from the program when the 
program writes a record to a display and are passed to the program when the 
program reads a record from the display and the field is selected for input. By 
default, these fields are underlined on the display. Output/input fields are 
usually used when the program displays data that can be changed by a user. 
To specify an initial value for a named output field, see “Specifying Default 
Values for Fields” on page 3-26. 


e Hidden fields are fields that are passed from and to the program but are not 
sent to the display. Hidden fields are useful in applications involving subfiles. 
For example, a subfile record can contain record key information in a hidden 
field. The hidden field cannot be seen by the user, but is returned to the 
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program with the subfile record so that the program can return the record to the 
database. 


¢ Constant fields are fields that are passed to the display but are unknown to 
the program. These fields are unnamed and have their constant values defined 
in the DDS for the file. DATE, TIME, and MSGCON are examples of keywords 
that are allowed only on constant fields and whose constant values are deter- 
mined during program run time (DATE and TIME) or DDS compile time 
(MSGCON). 


¢ Message lines are output fields that are treated as messages. 


¢ Program-to-system fields are output-only fields that are named, numeric or 
alphanumeric. They are used to communicate between an application program 
and the system. Program-to-system fields do not appear on the display. That 
is, your program can place data in these fields and the system will use that 
data to control its processing on an output operation, but the user cannot see 
the contents of these fields. 


A field is input-capable if it is an input field or an output/input field. Each input- 
capable field has a special attribute called a modified data tag (MDT). The MDT 
is set on by the display station when any data is typed into the field. It can also be 
set on and cleared by the application program. 


The maximum number of fields that you can specify for each record format is 

32 763. (See “Understanding the Limitations on the Number of Input-Capable 
Fields” on page 3-39 for information on the number of input-capable fields that can 
be specified.) The maximum combined length for all fields and indicators in a 
record format is 32 763. 


The following display shows output fields and input fields displayed in response to a 
request (in the form of entering a customer number in an input field) from a user. 


(— =| 


Customer number: 41394 


Order number: 41882 

Order date: 11/01/81 
Order amount: $580.00 
A/R balance: $580.00 


Enter next customer number: 


— — 


The prompts, Customer number:, Order number:, Order date:, Order amount:, A/R 
balance:, and Enter next customer number: are constants. The data associated 
with these fields (41394, 41882, 11/01/81, $580.00, and $580.00) is displayed in 
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output fields. The data is passed from the application program to the system, and 
the system displays it. The field following the constant Enter next customer 
number: is an input field. The user must enter data into this field (the cursor is 
positioned at the beginning of the input field). Input fields are underlined by default. 
Editing of the field is normally defined within DDS. 


You must specify the location for each field except when the field is a hidden field, 
a message line, or a program-to-system field, or when the field is in a subfile 
message record format. You cannot specify line 1, position 1 for location, except 
when you define a record that can start in any line. 


The maximum length of a character field or numeric (zoned decimal) field is the 
number of positions remaining (relative to the start location of the field) on the 
display minus 1. Another restriction of the numeric (zoned decimal) field is that it 
can be no longer than 31, even if more than 31 positions are remaining on the 
display. 


Specifications for the fields you describe can be retrieved from a previously 
described field. The previously described field can be either in a database file or 
already defined in the DDS source for the display file. When you use field-level 
descriptions from a database file, binary and packed decimal fields are changed to 
zoned decimal fields. These fields that you use to define other fields are called 
reference fields. 


You can define two fields to occupy the same positions on the display, and use 
option indicators to select which of the overlapping fields is to be displayed. If 
more than one overlapping field is selected on the same output operation, only the 
first field selected is displayed. 


Defining Function Keys 
To write an application using a display station, you have to control both the func- 
tions of the keys at the keyboard, and the contents of the display. 


Display 
Contents 


see (L ] AN \ 


RV2W001-2 


The Enter key can always be used by the user. So that the user can use the other 
function keys, you must specify the following DDS keywords to enable the corre- 
sponding function key: 


e CAnn, where nn is 1-24 
e CFnn, where nn is 1-24 
e CLEAR 
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e HELP (not required if you only need the Help key to retrieve the message help 
on the display) 

¢ HOME 

e¢ PRINT 

e ROLLDOWN or PAGEUP (not required to be able to roll a subfile when the 
subfile page is not equal to the subfile size) 

e ROLLUP or PAGEDOWN (not required to be able to roll a subfile when the 
subfile page is not equal to the subfile size) 

¢ MOUBTN (Programmable Mouse Button) allows attention identifiers to be asso- 
ciated with various pointer device events. 

e PSHBTNFLD (Push Button Field) allows an attention ID to be associated with a 
push button. 


To tell which function key is pressed when you perform the read operation, you 
need to define your function keys using one of the following: 


e Define a response indicator for the function key. A response indicator is an 
indicator that returns information back to an application. There are 99 
response indicators available to you. 


Note: Response indicators are used for more than function keys. For 
example, you can use them to tell when the data in a field on the 
display has changed. 


e Examine the input/output feedback area. The input/output feedback area is 
status information provided by the system about the operations performed on 
an opened file. To find out how to get information from the input/output feed- 
back area, see the manual for the programming language you are using. See 
Appendix C, “Feedback Area Layouts for Display Files” on page C-1 for a 
description of the information available from the feedback areas. 


Defining Command Attention (CAnn) and Command Function (CFnn) 


Keys 


The command function (CFnn) keys and command attention (CAnn) keys are num- 
bered 1 through 24 and are the same physical set of keys on the keyboard. These 
keyboard keys are usually labeled Cmdnn or PFnn or Frnn, where nn is the associ- 
ated key number. They can be used to set a response indicator or to perform a 
certain function. 


The different command keys do the following: 


Command function A record containing changed fields is returned to the 
program. 

Command attention A record is returned to the program but the record does 
not contain the data entered by the user and no field vali- 
dation is performed. 


If a key is specified as a CFnn key in a file, it cannot also be specified as a CAnn 
key in the file. Likewise, if it is specified as a CAnn key, it cannot also be a CFnn 
key. For example, if function key 01 is specified as a CAnn key (CA01), you 
cannot specify CF01 anywhere in the same file. 


If a response indicator is specified for a CFnn key and the key is pressed, the 
response indicator is set on and passed to the program with the input data. Ifa 
response indicator is not specified for a CFnn key, only the input data is passed. 
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Note: The input/output feedback area contains the 1-character attention identifier 
(AID), which also identifies the key pressed. See Appendix C, “Feedback 
Area Layouts for Display Files” on page C-1 for a description of the 
input/output feedback area. 


If a response indicator is specified for a CAnn key and the key is pressed, the 
response indicator is set on and passed to the program. Fields sent to the display 
and hidden fields are returned to the program. If a CFnn key or the Enter key was 
previously pressed, the input-only field is returned as previously typed data. If data 
was never entered into an input-only field, the field is returned as blanks (character 
field) or zeros (numeric field). Fields changed by the user since the last time a 
CFnn key or Enter key was pressed are not returned. 


The use of CAnn keys can cause the input buffer of the program to contain user- 
entered data that does not meet the validation specified in the display file. For 
example, the user enters data and presses a CFnn key or the Enter key, and the 
data is validated as defined in your DDS. Input data is processed one field at a 
time with data manipulation taking place before the validity checking. If a validity- 
checking error occurs, a message is selected and all the other input data is pro- 
cessed. After all input data is processed and one or more errors have occurred, a 
message is sent to the user. Then, if the user presses a valid CAnn key, no 
changed data is sent from the display. The data is moved from the input buffer 
save area to the input buffer. The input buffer now contains the data that is in 
error. If your program is not going to process this data when the CAnn key is 
pressed, you do not have a problem. If this is a problem, avoid using CAnn keys; 
only use CFnn keys so that data that is not valid can be detected. 


If you want to use CAnn keys, you should not specify the following validity-checking 
DDS keywords: 


CHECK(M10) 
CHECK(M11) 
CHECK(VN) 
CHECK(VNE) 
CHKMSGID 
COMP/CMP 
RANGE 
VALUES 


The Print, Help, Clear, and Home keys operate in the same manner as the CAnn 
keys. The Roll Up, Roll Down, Page Up, and Page Down keys operate in the 
same manner as CFnn keys. 


Specifying Alternative Keys 
You can also define command attention or command function keys to perform the 
functions of the Help, Page Up (or Roll Down) and Page Down (or Roll Up) keys. 
The function key specified on the keyword identifies the alternative key to be used. 


The DDS keywords are: 


¢ ALTHELP: Indicates that the help function will be started when either the Help 
key or the key specified on the ALTHELP keyword is pressed. If the ALTHELP 
keyword is specified but an alternative key is not specified, the default is CA01. 
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Note that the Help key is an attention key, not a function key, because it does 
not return input. 


e ALTPAGEUP and ALTPAGEDWN: Indicate that the paging functions will be 
started when the page keys or the keys specified on the keywords are pressed. 
If alternative keys are not specified on the ALTPAGEUP or ALTPAGEDWN 
keywords, the defaults are CFO7 and CFO08, respectively. Note that the page 
keys are function keys, because they return input. 


The alternative keys specified on the ALTHELP, ALTPAGEUP, and ALTPAGEDWN 
keywords provide the same function as the actual keys. For example, if pressing 
the Help key starts the help function, then pressing the alternative key defined by 
the ALTHELP keyword will also start the help function. Likewise, if pressing the 
Page Up or Page Down key returns control to the application program, then 
pressing the alternative key will also return control to the application program. Both 
of these examples appear to the program as if the actual key was pressed. 


The user profile option for paging (USROPT(*ROLLKEY)) applies to the PAGEUP, 
PAGEDOWN, ALTPAGEUP, ALTPAGEDWN, ROLLUP, and ROLLDOWN 
keywords. 


The alternative help key function does not work when the keyboard is locked. For 
example, if you type information into a field that is not input-capable, a controller- 
detected error occurs and flashing numbers appear. The Help key can be used to 
get more information about the error. The function key specified as the alternative 
help key will not be valid until the Reset key is pressed, and then the help informa- 
tion will no longer be available. 


Passing Information via Indicators 


Indicators are one-character fields that exist either in the input records and output 
records used by the program or in a special indicator area. An indicator is on if it 
has the value 1 and off if it has the value 0. You can use indicators to pass infor- 
mation from a program to the system or from the system to a program. You 
specify how indicators are to be used through the DDS for the display file. 


There are two types of indicators for display files: 


Option indicators: Pass information from an application program to the 
system. These typically are used to control the pro- 
cessing of a particular record format by the system. 


Response indicators: Pass information from the system to an application 
program when an input request completes. Response 
indicators can inform the program which function keys 
were pressed by the user or whether data was changed 
by the user. 


Both option and response indicators can be specified at the file level, record format 


level, and field level. Indicators specified at the file level apply to all record formats 
within the file. 
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Removing Option and Response Indicators from the Record 
Area 

You can use the Indicator Area (INDARA) keyword to separate the option and 
response indicators from the input and output records used by the program. If you 
use the INDARA keyword, the indicators are placed in a separate 99-character 
area; see your appropriate high-level language manual for information on how this 
99-character area is defined. 


If you use the same indicator number as both a response indicator and as an 
option indicator, you can use the status of the response indicator to set the option 
indicator for a subsequent output operation. For example, indicator 15 is used as 
both a response indicator and an option indicator. If the response indicator is on 
when an input operation is performed on the record format, option indicator 15 is 
set on and will be on when an output operation is performed for that record format. 


The maximum number of record formats that you can define for a display file is 
1024. If you do not use the INDARA keyword, the maximum number of fields that 
you can specify depends on the number of indicators (1 character each) you use 
and the length of each field you describe. The total combined length of all fields 
and indicators in a record format cannot exceed 32 763 characters. If you use the 
INDARA keyword to specify a separate indicator area, the maximum number of 
fields that you can specify depends only on the length of each field. The total 
number of all fields cannot exceed 32 763. 


Enabling Different Response Indicators Simultaneously 

It is possible to have different response indicators for the ROLLUP/ROLLDOWN 
keywords on record formats displayed at the same time. For example, record A 
has specified a roll-up indicator of 52 and record B has specified a roll-up indicator 
of 25 and both records are displayed. When a read operation is requested to 
record A in your program, the operator presses the Roll Up key which returns 
control to your program. Record A is passed to your program with response indi- 
cator 52 set on; response indicator 25 is not set. Your program can then do a read 
operation to record B. When record B is passed to your program, response indi- 
cator 25 is set on; response indicator 52 is not set. Only the response indicator 
specified on the record format for which the read operation is done is set. The 
record format in which the cursor was located when the Roll Up key was pressed 
does not affect the setting of the response indicator associated with the ROLL 
keyword. 


Setting an Indicator Off 

An indicator specified on the SETOF or SETOFF keyword becomes a response 
indicator that is set off and returned to the program. The indicator is not set off 
until an input operation is performed. If the same indicator is specified elsewhere in 
the record format as a response indicator, the indicator is returned to the program 
based on the status of the associated keyword condition. For example, if response 
indicator 01 is specified both for the SETOF/SETOFF keyword and the CF5 key, 
indicator 01 is returned in the on condition when the CF5 key is pressed. If the 
indicator is specified elsewhere as a response indicator, there is no need to use the 
SETOF/SETOFF keyword. 
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Inserting Constant Field Text from a Message Description 
You can specify that the text for constant fields is contained in a message 
description using the Message Constant (MSGCON) keyword. 


If the message description used for the constant text is shorter than the field on the 
display, the remaining portion of the field is padded with blanks. If the message 
description is longer than the field, the message description is truncated. 


If the messages description does not exist when the DDS is compiled, the file is not 
created. If you change the message description, you will have to create the file 
again if you want the display file to contain the updated messages. 


Allowing for Right-to-Left Cursor Movement 


The cursor can be made to move from right to left on the display between fields 
and in input fields. Two parameters for the DDS CHECK keyword can be used to 
do this: 


¢ CHECK (RL): Moves the cursor from right to left in specified nonnumeric input 
fields or all nonnumeric input fields on the display. 


e CHECK (RLTB): Moves the cursor from right to left between fields. 


When using these parameters, remember the following: 


e¢ Modulus check digit verification is supported, but the check digit is still the byte 
to the extreme right of the field. 


¢ A field for which right-to-left cursor movement is specified can occupy more 
than one line on the display. However, the cursor still moves from the top of 
the display to the bottom. 


e You cannot use right-to-left cursor movement with user-defined data streams. 


Note: If no cursor positioning is specified in the display file or by the program, the 
cursor is placed in the input-capable field to the extreme left of the top line. 


Defining Cursor Movement to Input-Capable Positions Only 


Use the cursor input only (CSRINPONLY) keyword to restrict cursor movement to 
input-capable positions only. This keyword affects only the cursor arrow keys. This 
function moves the cursor to the first input-capable position on a display in the 
direction of the arrow key. The user needs to press the cursor key only once in the 
appropriate direction to have the cursor move to the input-capable position. 


Specify this keyword at the file or record level. 


The input-capable positions to which the cursor can move include the following: 
e Input field (except protected fields) 


¢ Selection-field choice (except those on which you cannot place the cursor 
because of its choice control (CHCCTL) value) 


¢ Selection-list choice (except those on which you cannot place the cursor 
because of its choice control (CHCCTL) value) 


e Message line (if a message is displayed and the keyboard is not locked). 


¢ Message subfile defined with the subfile message record (SFLMSGRCD) 
keyword. 
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Several DDS keywords (such as DSPATR(PC) and CSRLOC) can be used to posi- 
tion the cursor at any display position. This is true even if the CSRINPONLY 
keyword is specified. The first subsequent cursor movement keystroke will move 
the cursor to a cursorable location. If no cursorable position exists on the display, 
the cursor will be positioned to row 1, column 1. Once the cursor has been moved 
from this position, pressing the home key repositions the cursor back to its initial 
position. 


If a window is displayed with no input fields, the cursor is positioned at row 1, 
column 1 of the window. If a cursor movement key is pressed, the cursor moves to 
row 1, column 1 of the full display (outside the window). If the window is defined 
with “*RSTCSR, command keys are not valid outside the window. Pressing the 
home key returns the cursor to the window. Pressing any command key or the 
Enter key sounds an alarm and returns the cursor to the window. To avoid this 
problem, consider specifying an input inhibited input field in the upper corner of the 
window or specifying *NORSTCSR on the window keyword. 


Notes: 


1. If a message subfile is defined with a SFLPAG keyword greater than 1 and the 
CSRINPONLY keyword is in effect, any fields that have been turned to reverse 
image because of an error, will be turned to unreverse image if the message 
subfile is rolled to a partial page of messages. 


2. Fields that have been turned to reverse image because of an error are turned 
to unreverse image when the following conditions are true: 


¢ A message subfile is defined with a SFLPAG keyword greater than 1 
¢ The CSRINPONLY keyword is in effect 
e¢ The message subfile is rolled to a partial page of messages 


3. When a record is written with the PUTOVR, ERRMSG, or ERRMSGID 
keywords in effect, the state of the CSRINPONLY keyword is not changed. If 
the CSRINPONLY keyword is in effect prior to the write operation with the 
PUTOVR, ERRMSG, or ERRMSGID keywords, the CSRINPONLY remains in 
effect. This is true regardless of the optioning of the CSRINPONLY keyword 
on the record assigned the PUTOVR, ERRMSG, or ERRMSGID keywords. 
This is also true regardless of the optioning of the PUTOVR, ERRMSG, or 
ERRMSGID keywords on the record assigned the CSRINPONLY keyword. 


4. Writing a record with the PROTECT keyword does not affect the input fields 
associated with messages when the CSRINPONLY keyword is in effect. Any 
messages displayed are not protected. Therefore, the cursor may still be 
moved the messages. 


5. The CSRINPONLY keyword is valid only for display stations attached to a con- 
troller that supports an enhanced interface for nonprogrammable work stations. 
It is ignored on display stations attached to other controllers. 


Defining Cursor Progression for Entry Fields 
The FLDCSRPRG keyword lets the user specify the next field the cursor should 
move to when the cursor leaves a field. 


The DDS for the field looks like this: 
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A Fl 10A B 3 4FLDCSRPRG(F3) 
A F2 10A B13 4FLDCSRPRG(F1) 
A F3 10A B16 4FLDCSRPRG(F2) 


Figure 2-3. DDS for Field-Level Cursor Progression 


The parameter for the FLDCSRPRG keyword is the name of the field the cursor will 
go to when forward field-exit processing is performed. When the cursor leaves F1 
because of a field exit key, it goes to F3. If the field named with this keyword is 
optioned off, cursor progression for this field is ignored. 


Note: When the cursor leaves a field using backward field-exit processing, the 
cursor moves to the first field on the display that has the exited-field name 
specified on the FLDCSRPRG keyword. For the DDS in Figure 2-3, if 
backward field-exit processing is used to leave field 2, the cursor moves to 
field 3. 


SFLCSRPRG is the keyword used for subfile cursor progression. The DDS for 
subfiles looks like this: 


loovteypelve dehy eee pet esd edwin e sedan cab eGo8 eh waeeOaaeeivece Loan 
A R SFLO1 SFL 
A S1 10A B 5 5SFLCSRPRG 
A 82 10A B 5 25 
A R CTLO1 SFLCTL(SFLO1) 
A SFLPAG(5) SFLSIZ(20) SFLDSP 


Figure 2-4. DDS for Subfile-Level Cursor Progression 


The SFLCSRPRG keyword causes the cursor to move from a field in a subfile 
record to the same field in the next displayed subfile record. Without 
SFLCSRPRG, the cursor moves from a field in a record to the next field in the 
same record. When the cursor leaves field S1 of the first record of the subfile, it 
goes to S1 of the second record of the subfile. Without the SFLCSRPRG keyword, 
the cursor goes to field S2 of the first record. When the cursor leaves S2, it goes 
to S1 of the next record because S2 does not have the SFLCSRPRG keyword. 
This keyword is not allowed with subfiles that use field selection. It cannot be used 
with horizontal subfiles. When the cursor is on S1 of the last SFL record displayed, 
the cursor moves to the next input field below the last SFL record. If there are no 
remaining SFL fields, the cursor moves to the top of the display. 


Note: The FLDCSRPRG keyword and the SFLCSRPRG keyword are ignored on 
displays that are attached to a controller that does not support an enhanced 
interface for nonprogrammable work stations. 


Defining Attributes for Entry Fields 
An entry field’s leading field attribute is changed to a specified attribute when the 
cursor enters the field. 


The DDS for the field looks like this: 


| wogtinivpleweetycgsloseth esa d ovat eyes deyesteee. BurwatpcrsOyerstussel ete 
A Fl 10A B 3  4ENTFLDATR(*CURSOR (*DSPATR CS)) 
A F2 10A B13 4ENTFLDATR(*NOCURSOR (*COLOR RED)) 
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ENTFLDATR tells the system to change the attribute of the field when the cursor 
enters the field. “CURSOR and *NOCURSOR are used to specify whether the 
cursor is visible when it enters the field. If the “NOCURSOR option is specified, the 
cursor row and column values in the input-output feedback area indicate the first 
position in the field. You can also specify a color or an attribute. 


Note: The ENTFLDATR keyword is ignored on displays that are attached to a 
controller that does not support an enhanced interface for nonprogrammable 
work stations. 


Protecting Entry Fields Using Edit Masks 


The EDTMSK keyword is a new DDS keyword for fields with EDTCDE or EDTWRD 
keywords. When the field is displayed, certain areas of the field will be protected. 
You define which areas to protect. 


The DDS for the field looks like this: 


| evetdacedaosetied.2eocwhaessdeadcby anil ces whee so Sees eh ieaNOr ae tises lees 
A Fl 6 0B 3 4EDTWRD(' / / ') 
A EDTMSK(' & & ') 
A F2 6 0B 4 4EDTCDE(Y) 
A EDTMSK(' & & ') 


The ampersand (&) represents a protected part of the field. A blank represents an 
unprotected part of the field. The length of the edit mask must equal the display 
length of the field. The number of unprotected positions must at least equal the 
program length of the field. You must only protect nonnumeric data because pro- 
tected data is not returned if the field is changed. Wherever there is an &, that part 
is protected no matter what data is in the field. 


The first field has the slash (/) characters protected in a date. For the second field, 
the / in the date is always protected. 


Keyboard functions on displays attached to a controller that supports an enhanced 
interface for nonprogrammable work stations are the same for edit-mask fields as 
they are for continued-entry fields. 


Note: The EDTMSK keyword is ignored on display stations attached to a con- 
troller that does not support an enhanced interface for nonprogrammable 
work stations. 


Specifying Right-to-Left Display Processing 
You can specify that records in a display file be written in the right-to-left direction 
by using the Display Right-to-Left (DSPRL) keyword. This keyword is allowed only 
at the file level. 


Figure 2-5 shows an example of the DDS coding. 


A DSPRL 
A R RECORD 
A FLD1 20A 5 5')Customer Name(:' 


Figure 2-5. Sample DDS for Right-to-Left Display Processing 
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The DDS in Figure 2-5 produces this output on the display: 


:(emaN remotsuC) 


Notice that the left and right parentheses in the DDS are reversed; this is so they 
appear correctly on the display. All symmetrical characters have to be specified in 
this way. 


If your application program uses one display file with the DSPRL keyword and 
another display file with the WINDOW keyword, make sure that the display file with 
the WINDOW keyword also specifies the DSPRL keyword. Otherwise, the display 
assumes the orientation of the display file that has the WINDOW keyword. 


If you specify the DSPRL keyword, the cursor moves from right to left when you 
enter data. Therefore, it is not necessary to use the CHECK(RL) keyword. If you 
specify CHECK(RL) and DSPRL, the CHECK(RL) keyword is ignored. 


The DSPRL keyword causes all records in a display file to be written in the right-to- 
left direction. You cannot specify that individual records be written in the left-to- 
right direction. 


If you specify the ERRMSG or the ERRMSGID keywords with the DSPRL keyword, 
the messages associated with these keywords display in the left-to-right direction. 


Specifying Word Wrap for Fields 


Word wrap is the function that automatically moves the last word in a field down to 
the next line in the field if the word runs beyond the right margin of the field. To 
specify the word wrap function for a named field, use the word wrap (WRDWRAP) 
keyword. This keyword can be used at the file, record, or field level. It can only be 
used with input-only (I) or output/input (B) fields. 


Notes: 


1. This function is available only for display stations attached to a controller that 
supports an enhanced interface for nonprogrammable work stations. 


2. The Reverse key and the Close key cannot be used in a word wrap field. 
3. When word wrap is used and the keyboard is in insert mode, null characters 
are not shifted to the right; they are replaced. 
Word wrap is not allowed for these fields: 


¢ DBCS-only fields 

e Pure fields 

e Either fields (with double byte) 
¢ Open fields with SBCS data 


Word wrap is not allowed with the following field types or features: 


e¢ Signed numeric 
e¢ Numeric only 
¢ Digits only 
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e Magnetic Stripe Reader (DSPATR(OID)) 

e Light Pen (DSPATR(SP)) 

e Right-justify 

e Mandatory fill 

¢ Self-check (M10F/M11F) 

¢ Dup allowed 

e Right-to-left cursor movement (CHECK(RL)) 

e Right-to-left, top-to-bottom cursor movement (CHECK(RLTB)) 


If all the data cannot fit within a word wrap field without splitting words, the word 
wrap function for that field is ignored. The data is written as if word wrap had not 
been specified. The subsequent operation of the field is also as if word wrap were 
not specified. 


Word wrap may be specified on fields that are contained on a single line. In this 
case, when the keyboard is in insert mode, null characters are not shifted to the 
right; they are replaced. 


Specifying Word Wrap for Fields—Tips 
Some things to consider when using the word wrap function: 
e The total length of the input field should allow for character positions at the 


ends of lines or segments to be used for padding when a wrap occurs. Ifa 
field is too short, errors will occur or word wrap will be turned off. 


e The length of each line or segment should be as large, or larger than the 
longest word that may be entered in the field. If a line or segment is too short, 
errors will occur or the data may be shifted down to the last line or segment. 


e Extra blanks that are inserted to make a wrap occur are removed when data is 
returned to your program. 


Emphasizing Fields 
You can emphasize a field of a record on the display by specifying the following in 
the DDS for the file: 


Note: Any function not supported for your display station is ignored. 


Table 2-2. DDS for Emphasizing Fields 


Type of Emphasizing DDS keyword 
Underlining a field (the default for input fields) DSPATR(UL) 
Placing vertical separators between the characters in a field DSPATR(CS) 
Highlighting a field by displaying it with greater intensity than is DSPATR(HI) 


normally used on the display 


Reversing the image of a field from light on dark to dark on light or DSPATR(RI) 
from dark on light to light on dark 


Making the data in the field invisible to the display station user DSPATR(ND) 
Placing the cursor at a specific field DSPATR(PC) 
Blinking a field when it is displayed DSPATR(BL) 


Another way of specifying attributes for a field is by using a program-to-system field 
parameter on the DSPATR keyword. Your application program uses the program- 
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to-system field to set the display attributes or protection attribute for the field to 
which the DSPATR keyword applies. 


Figure 2-6 shows an example of the DDS coding for program-to-system fields: 


| costtaces Deve ehaay eleven teeta Saves tes cod duwekey ve Svenetines Ov ace tease? vee 


A R RECORD 

A FLD1 5A 2 2DSPATR(&PFLD1) 
A FLD2 5A 2 9DSPATR(&PFLD2) 
A PFLD1 1A P 

A PFLD2 1A P 


Figure 2-6. Sample DDS for Program-to-System Fields 


One program-to-system field may be used for multiple fields within a record. Only 
one program-to-system field can be used per field. You cannot specify the fol- 
lowing attributes using the program-to-system field: 


MDT Set changed data tag when displayed 
OID Operator identification 

PC Position cursor 

SP Select by light pen 


For the valid hexadecimal values that your program can pass to the program-to- 
system field, see the DDS Reference. 


Adding Color 


You can design your displays for use on display stations that show color. The DDS 
keyword COLOR allows you to specify the following colors for fields: green, white, 

red, turquoise, yellow, pink, and blue. This keyword is ignored if it is selected for a 
field displayed on a display station that does not support color. 


If the COLOR keyword is not specified in the DDS for the display file but the 
display station is specified in the display station description as a color display 
station, displays that you have designed for display stations that do not support 
color can also be used for the color display station. The keywords DSPATR(UL) 
and DSPATR(RI), if specified on separate fields, function the same as they do for 
the 5250 display station. However, the keywords DSPATR(CS), DSPATR(HI), and 
DSPATR(BL) produce the following colors on a color display station (the specified 
display attributes CS, HI, and BL are suppressed): 


Color Produced on the Display Display Display 
Color Display Station Attribute Attribute Attribute 
when No COLOR Keyword Selected: Selected: Selected: 
is Specified DSPATR(CS) DSPATR(HI) DSPATR(BL) 
Green (normal) 

Turquoise Xx 

White X 

Red, no blinking Xx 

Red, blinking X xX 
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Color Produced on the Display Display Display 


Color Display Station Attribute Attribute Attribute 
when No COLOR Keyword Selected: Selected: Selected: 
is Specified DSPATR(CS) DSPATR(HI) DSPATR(BL) 
Yellow xX Xx 

Pink X X 

Blue xX Xx Xx 


Editing Output Fields 


The system provides editing support that makes fields more readable when they 
are displayed. With the system editing support, you can do the following: 


¢ Suppress leading zeros 

e Punctuate a field with commas and periods to show decimal column and to 
group digits by threes 

e Show negative values with a minus sign to the left or right 

e Show negative values with the letters CR (credit) to the right 

¢ Show zero values as zeros or blanks 

¢ Show asterisks to the left of significant digits to provide asterisk protection 

e Show a currency symbol corresponding to the system value QCURSYM 


The system provides this editing support with edit codes and edit words. Edit 
codes are a defined set of editing patterns. In addition to those provided by the 
system, you may also define your own edit codes. You identify edit codes by 
name, and the system edits a field according to the pattern defined by the named 
edit code. Edit words are edit patterns that you define to produce the desired 
results. Edit codes cover most commonly used editing requirements. You need to 
use the edit word support only for those editing needs not covered by edit codes. 


Edit codes are used as follows: 


¢ lf your application is using program-described data, your high-level language 
may allow you to identify edit codes or create your own edit words. 

e lf your application is using externally described data, the edit code (EDTCDE) 
DDS keyword allows you to identify an edit code, and the edit word (EDTWRD) 
DDS keyword allows you to define your own editing pattern. 


The system provides several edit codes. The editing patterns defined by these 
codes are contained in Appendix F, “Edit Codes.” 


Defining Your Own Edit Codes 
You can define five edit codes to provide more editing function than is available 
with the OS/400* edit codes, and to handle common editing functions that would 
otherwise require the use of an edit word. These are called user-defined edit 
codes. For example, you may need to edit numbers that include hyphens (like 
some telephone numbers), or more than one decimal point. You can use user- 
defined edit codes for these functions. These edit codes are named QEDIT5, 
QEDIT6, QEDIT7, QEDIT8, and QEDIT9Y and can be referred to in DDS or a high- 
level language program by number (5, 6, 7, 8, or 9). 


These edit codes are created by using the Create Edit Description (CRTEDTD) 
command. Edit descriptions are always placed in library QSYS. They cannot be 
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moved or renamed; only one occurrence of each is allowed. Edit descriptions have 
an object type of *EDTD. 


Even though they are user-defined edit codes, your system comes with a version of 
each one of them. You can use these edit descriptions as they are, or you can 
delete them and create your own. The editing performed by the IBM-supplied ver- 
sions of these edit descriptions as well as a definition of the contents of and the 
rules for using any user-defined edit code are described in Appendix F, “Edit 
Codes.” 


Before using any of the user-defined edit codes, you should check its contents on 

your system, since it may have been changed from the IBM-supplied version. The 
Display Edit Description (DSPEDTD) command will display the contents of a user- 
defined edit code. 


Changing a user-defined edit code description does not affect any application or 
display file that has already been created using that edit description. If you want 
your application to use the changed edit description, you must either create the 
high-level language program again (if the edit code is referred to in the program) or 
create the file again (if the application is using an externally described file that con- 
tains EDTCDE keywords). 


Specifying Valid Screen Sizes 


In some cases, you can use the following screen size condition names to select 
keywords and display locations based on screen size: 


¢ *DS3, 24 by 80 (5251 Models 11 and 12, 5291, 5292, 3179 Model 2, 3180-2, 
3196, and 3197) 

¢ *DS4, 27 by 132 (3180-2; 3197 Models D1, D2, W1, W2; 3477 Models FA, FC, 
FD, FE, FG, FW; 3487 Models HA, HG, HW, HC) 


Note: The capability to display in 27 by 132 mode is allowed on 3180-2, 3197, 
3477 Models FA, FC, FD, FE, FG, FW, and 3487 Models HE, HD, HW, 
HC display stations attached to a 6040 or 6041 or 2638 local display 
station controller, or remotely attached to a 5294 or 5394 controller. 
The display size for 27 by 132 mode is ignored for the DSPSIZ keyword 
unless these controllers are specified. 


These condition names can be used to place fields in different locations on different 
sizes of screens. However, the fields must still be specified in the same order on 
each size of screen. For example, the following DDS formats a display for both a 
24 by 80 screen and a 27 by 132 screen: 
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[euccthos weds wis teeys Ove wet soe des oot cgwe dey obese 2Seeeooies Orc 2e4eesT one 


A DSPSIZ(*DS3 *DS4) 
A : 

A 

A 

A R RECORD 

A NAME 20 5 2 

A *DS4 3112 

A ADDR 30 6 2 

A *DS4 4102 


Figure 2-7. Sample DDS for Two Display Sizes 


Normally, the display files are set up for a 24 by 80 screen (default size). The 
DSPSIZ keyword specifies which display sizes are valid for a file and indicates 
which sizes are the primary and secondary screen sizes. (The primary screen size 
is the first or only DSPSIZ value.) On the DSPSIZ keyword, the screen size can be 
specified as *DS3, *DS4, 24 80, or 27 132. For example, DSPSIZ (24 80) specifies 
a screen size of 24 by 80. When primary and secondary display sizes are speci- 
fied, the display file is validated for both sizes. 


The screen size designated as the primary screen size should be the one with 
which the display file will most often be used. A performance benefit will be real- 
ized by coding the DSPSIZ keyword in this manner. Additional processing is per- 
formed when the actual screen size is the secondary screen size. 


The screen size condition names let you improve the use of a single display file for 
any size screen. For example, when you are using subfiles, you can specify 22 
records per page for a 24 by 80 screen or 25 records per page for a 27 by 132 
screen: 


[gertheaed die cathe taht eee ges Sends Ae oh tert Oe set eg aut 
DSPSIZ(*DS4 *DS3) 


SFLPAG(25) 
*DS3 SFLPAG(22) 


rPrrrrrrrTr,TE 


Figure 2-8. Sample DDS for Subfiles for Two Display Sizes 


You can also define your own screen size condition names. 
Enabling Your Display to Be Printed 
If the Print key is enabled for your display, the user can print the current display by 


pressing the Print key. The parameter (or lack of parameter) you specify for the 
DDS PRINT keyword controls how your display is printed: 
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Table 2-3. PRINT Keyword Results Using Print Key 


Parameter Action 


No parameter The output goes to the display station printer associated with 
this display (the PRINTER parameter on the Create Device 
Description for Display (CRTDEVDSP) or Change Device 
Description for Display (CHGDEVDSP)). If the operation to the 
display station printer fails or if there is no display station 
printer specified, the output goes to the printer file specified on 
the PRTFILE parameter on the display station description. 
The default for the PRTFILE parameter is QSYSPRT. 


File name and, optionally, The print operation is directed to the specified printer file. If 

library name the operation fails, it is directed to the default printer file, which 
is specified on the PRTFILE parameter on the CRTDEVDSP or 
CHGDEVDSP command. 


Response indicator Control returns to the program with the response indicator set 
on. 
*PGM Control returns to the program which must check the attention 


identifier in the input/output feedback area to determine which 
key was pressed. 


The PRINT keyword can be used at the file level and also at the record level. 
When PRINT is specified at the record level, several records with different forms of 
the PRINT keyword (or with no PRINT keyword) may be displayed on the screen at 
the same time. The last record format written to the screen controls the use of the 
Print key for the entire screen. 


If you specify the PRINT keyword in any form, the user can print a display con- 
taining the message help. 


The PRTKEYFMT parameter allows you to control what information is included 
when you print your display: 


¢ Output only 

¢ Output with header information (rows and columns) 

¢ Output with border information (title lines, which include the system name, date 
and time, and formatted user and display device name) 

¢ Output with both border and header information 


The PRTKEYFMT parameter on the Change Job (CHGJOB) and Retrieve Job Attri- 
butes (RTVJOBA) commands allows you to select how you want your Print key 
output to look. 


When you change the device description of a display station printer (by using the 
CHGDEVPRT command or the DLTDEVD and CRTDEVPRT commands), you 
should also change the device description of the associated display station, using 
the PRINTER parameter on the CHGDEVDSP command. You should do this even 
if the name of the printer, whose device description you changed, remains the 
same. 


2-26 Application Display Programming V4R1 


Defining Windows 


There are applications that could make use of a window on the display to assist the 
user in entering data. 


A window is information that overlays part of the current display and allows the 
user to read the information inside the window. The remainder of the display is not 
overlaid by the window and can still be read by the user. 


You can create windows by using standard DDS or by using user-defined data 
streams. To use standard DDS, see Chapter 5, “Defining Windows with Display 
Files” on page 5-1. Examples are also available in the QUSRTOOL library. 


Using Program-Described Data 


You can create a display file without using data description specifications. Such a 
display file then uses program-described data, and has no record or field level 
descriptions of its own. 


When you are using program-described data with a display file to communicate with 
one or more display stations, only simple display formatting can be performed, and 
that formatting must be specified in the high-level language program that is using 
the file. All field descriptions are defined and all processing is performed in the 
program that uses the file. More than one display file can be opened to the same 
display station at the same time within the same program, but only two can be used 
on the same display station at the same time: one for input and one for output. 


When a display file that uses program-described data is opened, the system treats 
the area on the display as a single field. That is, the field length is the same as the 
record length. The record length is defined by the program that is using the file, 
and stays the same from the time the file is opened until it is closed. Indicators 
cannot be passed when records are passed from the program to a display station, 
or from the display station to a program. Also, command keys cannot be used for 
program-described display files. 


The space on the display is assigned to program-described display files as shown 
in the following example. 


Records for the first file used by the program appear on the first (top) part of the 
display. Records for the second file appear on the display immediately following 
the area used by records in the first file. 


Record from file A \ First File Used By Program 


Record from file B } Second File Used By Program 


Unused Area 


RSLH705-0 
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The record from file B starts at the beginning of the first full line after the last line of 
the record from file A. If the record from file A does not completely fill its last line, 
the space is used by neither record and must be accounted for when calculating 
the maximum record lengths. In program-described display files, the maximum 
record lengths are: 


¢ For an input file, the screen size minus 2 

e For an output file, the screen size minus 2 

e For an output/input file, the screen size minus 2 

e For two files (one output and one input), the screen size minus 3 


When a program-described display file is opened, it can be defined as: 


e Input only 
¢ Output only 
e Input and output 


Defining Input-Only Files 
When an input-only file is opened, the record is initialized to a single blank field on 
the screen. The cursor is positioned at the first position of the field and the user 
can type in any type of data. 


When the program reads the record, the input is passed to the program. The 
record is not erased from the screen. The cursor is again positioned at the first 
position of the record (field) and the keyboard is unlocked when the program reads 
the next record. The user can then type in the next record over the previous 
record. 


Defining Output-Only Files 
When an output-only file is opened, the record is initialized to a single blank field on 
the screen. When the program writes a record to the file, the record is displayed 
and the keyboard is locked. The user must press the Enter key before another 
record can be written to the file. Subsequent records written to the file erase the 
currently displayed record because only one record can be displayed for the output 
file. 


Defining Input and Output Files 


When an input and output file is opened, the record is initialized to a single blank 
field on the screen. The cursor is positioned at the first position of the file and the 
user can type in any kind of data. 


The program that is using the file can read records or write records in any 
sequence. Whenever a record is written to the file, the modified data tag is set off 
(to indicate that data was not entered into the field) and the keyboard is unlocked. 
If the user then enters data into the field, the modified data tag is set on. If the 
next operation is a write operation instead of a read operation, the data typed in by 
the user is written over and the modified data tag is set off again. 
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Chapter 3. Working with Display Files in an Application 


After you define your display file, you can use it in an application. This chapter 
discusses the operations performed when a display file is used in an application. 


Understanding How the System Allocates Resources 


When a high-level language program uses a display file, several operations require 
that the system allocate the resources needed to perform that operation. Allocating 
file resources causes the system to obtain a lock on a display file when it is 
opened. Multiple users then cannot use the same display file in conflicting ways. 
For example, the system will not allow you to delete a file while any application 
program is using it. 


File resources are allocated in two ways: 


e The system performs the allocation whenever an operation is requested that 
requires it. The following operations for display files require allocation: 


— Open: The file resources include the file description and the display 
station. More information about the open operation is found in “Opening 
Display Files” on page 3-2. 

— Acquire: The display station is allocated as a resource. More information 
about the acquire operation is found in “Acquiring a Display Station for I/O 
Operations” on page 3-2. 

— Starting a program on a remote system: The file resources include session 
resources needed for APPC/APPN*. 


e If you prefer to ensure that all the resources that are needed by a program are 
available before the program is run, you may use the Allocate Object (ALCOBJ) 
CL command in the job prior to running the program. 


When allocating resources, the system waits for a predefined time if the resources 
are not immediately available. If the resources do not become available within the 
time limit, the following happens: 


e If you are using the ALCOBJ command, the command fails. 
e If your program is performing a file operation, that operation fails and an error 
message is sent to the program message queue. 


You may attempt to use the error handling functions of your high-level language to 
try the operation again. For example, if an open operation fails because another 
job is using the display station associated with the file, you could retry the open 
operation later when the display station is no longer being used. 


The length of time that the system waits when allocating resources is specified on 
the ALCOBJ command and on the WAITFILE parameter of the CRTDSPF 
command. If the ALCOBJ command is used prior to running a program, then the 
value of the WAITFILE parameter is ignored because resources are available. If 
your application has error handling procedures for display station errors occurring 
on display files, you should specify a value other than *IMMED to allow the system 
to recover from the display station error. The system recovery procedures for the 
display station must be completed before your program can recover from errors due 
to the allocation of resources. 
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Opening Display Files 


The open operation connects a display file to a program for processing. 


When a display file is opened, usually one or more display stations are implicitly 
acquired, or automatically prepared for I/O operations, for the display file: 


Table 3-1. Display Stations Implicitly Acquired When Display Files Are Opened 


How the Display File is 
Defined When Opened 


Other Specifications Display Station Implicitly Acquired 


Defined with a single 
display station 


Defined with multiple 
display stations 


Defined with no display 
stations 


*REQUESTER specified Display station at which the user requested the program 


“REQUESTER not speci- Display station specified on the DEV parameter of the 


fied CRTDSPF, CHGDSPF, or OVRDSPF command 
Opened by a CL All display stations specified on the DEV parameter of 
program the CRTDSPF, CHGDSPF, or OVRDSPF command 
Opened by any high- The first display station specified on the DEV parameter 
level language other than of the CRTDSPF, CHGDSPF, or OVRDSPF command 
CL 

- None 


The value specified on the WAITFILE parameter for the CRTDSPF, CHGDSPF, or 
OVRDSPF command is used to determine how long the open operation should wait 
for file resources to become available so they can be allocated. If a file resource, 
such as a display station, does not become available and the wait time specified 
ends, the open operation fails. 


Implicitly acquiring a display station when the file is opened results in the following: 


e The screen is cleared completely and the cursor is placed in the upper-left 
corner of the display. 
e¢ The keyboard is unlocked. 


Any display station to be implicitly acquired at the open operation must be varied 
on. Switched-line display stations can also be acquired if they are in a vary-on- 
pending state. Also, a display station other than the *REQUESTER display station 
cannot be acquired if it is signed on. 


Acquiring a Display Station for I/O Operations 


The system implicitly acquires, or automatically assigns, a display station to a 
display file when the display file is opened. However, you may also acquire addi- 
tional display stations for your program using the acquire operation. The acquire 
operation is used in multiple display file applications or if you are performing error 
recovery in your application. 


A successful acquire operation results in the following: 


e The screen is cleared completely and the cursor is placed in the upper-left 
corner of the display. 
e The keyboard is unlocked. 
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The value specified for the WAITFILE parameter on the CRTDSPF, CHGDSPF, or 
OVRDSPF command is used to determine how long the acquire operation should 
wait for a display station to become available so it can be allocated. If a display 
station does not become available and the wait time ends, no display is acquired. 


A display station cannot be allocated unless it is varied on. Switched-line display 
stations can be allocated if they are in a vary-on-pending state. Also, a display 
station other than the *REQUESTER display station cannot be allocated if it is 
signed on. 


The system allows only one *REQUESTER display station to be acquired to any 
display file, including a multiple-device display file. 


If an acquire operation is not successful, the release operation is the only valid 
operation to the display station. 


Obtaining Information about Display Files and Display Stations 


You can obtain information about the open and I/O operations performed on an 
open display file, and attribute information about a display station you are using. 


Obtaining Information about Open and I/O Operations 


After a display file is successfully opened, the system keeps track of the status of 
the file in feedback areas. 


The open feedback area contains information about the display file after it has 
been successfully opened, including: 


e¢ Name and library of the display file 

¢ Number of rows and columns on the display 

e Name and library of the file after overrides have been applied 
e Information about the display station defined for the file 


The device definition list part of the open feedback area contains information 
about each device attached to the display file. 


The I/O feedback area contains information about the I/O operations performed on 
the display file after it has been successfully opened. The I/O feedback area has 
two sections: 


¢ The common feedback area contains information about I/O operations that 
were performed on the file. This includes the number of operations and the 
last operation. 

e The file-dependent feedback area contains file-specific information for display 
files, such as the major/minor return code and the amount of data received 
from a display station. 


As operations are performed on the display file, the feedback area is updated to 
reflect the latest status. 


There is one feedback area for each open file. An exception is for shared files, 
which share feedback areas as well as the data path between the program and the 
file. For more information on shared files, see “Sharing Display Files in the Same 
Job” on page 3-50. 
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Feedback areas can be used to provide information when errors occur. For 
example, when an error occurs with a display file, the program could determine 
predefined error handling operations based on the major/minor return code in the 
file-dependent feedback area. More information on major/minor return codes is 
available in Chapter 8, “Handling Messages and Errors for Display Files.” 


Some high-level languages on the system allow you to access the status and other 
information about the file against which operations are being performed. 


See Appendix C, “Feedback Area Layouts for Display Files,” for a description of all 
the information available from the feedback areas. 


Obtaining Attribute Information about Display Stations 


The get-attributes operation allows you to obtain the following information about a 
specific display station: 


Table 3-2. Information Available from the Get-Attributes Operation 


Information Details 


The specific model of the Valid only when the display station is acquired to the file 
display station 


The screen size of the Valid only when the display station is acquired to the file 
display station 


Device acquired indicator Indicates whether or not the display station is currently 
acquired to the file 


Device invite status Indicates whether or not the display station is invited, and if 
so whether or not the display station has data available; 
valid only when the display station is acquired to the file 


*REQUESTER display Indicates whether or not the display station is the 
station indicator “REQUESTER display station 


Since the information supplied is also available in the open and input/output feed- 
back areas for the display station that is implicitly acquired when the file is opened, 
the get-attributes operation is most useful for multiple display file applications. For 
more information on how to perform the get-attributes operation, see the appro- 
priate high-level language manual. 


See Appendix C, “Feedback Area Layouts for Display Files,” for a description of all 
the information available from the get-attributes operation. 


Sending and Receiving Data 


All data written to and read from the display by the application program is done with 
records. Records consist of fields, which are individual items of data. The high- 
level languages in which application programs are written have I/O statements that 
give data to the system to be written to the display and receive data from the 
system that it read from the display in the form of records. 


The I/O statements of the high-level languages also refer to record formats, which 
are defined using DDS. On output, a record format describes how the data given 
by the program is to be presented on the display as well as how the data is to be 
processed before presenting it. On input, the record format is used to control some 
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display functions, to extract the program data from all the data which is on the 
display, and to present that data back to the application program. 


-—— Information about DDS keywords 


This section uses DDS keywords that control sending and receiving information 
to the display. For more information about specific DDS keywords, see the 
DDS Reference. 


Determining Which Record Formats Are Active on a Display 


The system maintains the active record format table, a table of all record formats 
that are currently on the display. Read operations may take place against only 
those record formats that are in the active record format table. Certain DDS 
keywords cause records in the table to be altered. 


A record format is added to the table when a write operation that contains the 
record format is performed. A record format is removed from the table when a read 
operation can no longer be correctly performed for this record. 


The active record format table is cleared whenever the display is cleared. 


Writing Output to the Display 


A write operation passes a record from the program to the system. The record 
format in the display file contains the information necessary for the system to 
handle the record. The write operation results in the following: 


Write Operation 


(} HELLO HELLO 
————_> a 2 


(2-0) (— BOY (2-—A0d) 
o by Lb) 
Clears screen Writes record Unlocks 
to screen keyboard 
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Placing Records on the Display 
One record format can occupy an entire screen or the screen can be divided to 
display more than one record format. 


If a record is displayed on more than one line, the following rules apply: 
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e The lines must be consecutive lines on the display. For example, if one record 
occupies two lines and the record begins on line 2, the record must continue on 
line 3. 

¢ Only a beginning attribute character can occupy line 1, position 1. 

¢ If only the ending attribute character for the last field in a record is in position 1 
of the next line, another record format can begin on that same line. 

¢ Only one record can occupy a line on the display at a time. If you want to 
display a record format that overlaps one or more lines of a record format 
already on the display, specify *NO for the clear lines (CLRL) keyword. 
CLRL(*NO) clears the common lines before displaying the new record format. 


The following three figures show how screens can be divided when the CLRL 
keyword is not specified: 


Record FormatA 


RSLH199-0 


Figure 3-1 (Part 1 of 3). Valid Placement of Records on a Screen When the CLRL 
Keyword Is Not Used 
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Record Format A 


Record Format B 


ww v 7 
RSLH197-0 


Figure 3-1 (Part 2 of 3). Valid Placement of Records on a Screen When the CLRL 
Keyword Is Not Used 


a * >) 


Record FormatA 


Record Format D 


Record Format B 
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Figure 3-1 (Part 3 of 3). Valid Placement of Records on a Screen When the CLRL 
Keyword Is Not Used 


The following figure shows how screens cannot be divided when the CLRL 
keywords is not specified: 
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Record Record 
Format A Format B 


(Fields from different record formats cannot be displayed on the same line.) 


le Record FormatA rs] 
i Record Format B = 
Ke Record Format A 5 


+————Record Format A 


P| Id Record Format B & 


(Fields from different record formats cannot be displayed on the same line.) 
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Figure 3-2. Wrong Placement of Records on Screen When CLRL Keyword Not Used 


Understanding Which Records Do Not Occupy Space on the 
Display 

The following types of records do not occupy space on a display but are assumed 
to be at line 0: 


e Records with no fields defined 
e¢ Records with only hidden, program-to-system, or message fields 
e Records with the CLRL keyword specified and with no input-capable fields 


The system keeps track of only one of these records at a time. If an output opera- 
tion for a record assumed to be at line 0 replaces another record assumed to be at 
line 0, you can no longer issue an input operation for the replaced record. 


Changing Record Formats on a Display 
The formats displayed can change while a file is being processed because informa- 
tion on a display can be deleted when new formats are displayed. 


When your program displays a new record format for output or to allow input, the 
existing display is usually erased before the new record format is displayed. For 
example, if three record formats are on the display at the same time and you write 
another record to the display, the three record formats on the display are erased. 
Several DDS keywords, such as the OVERLAY keyword, let you control the dis- 
playing of records and input fields on input and output operations. For more infor- 
mation about these DDS keywords, see “Overlaying and Erasing Record Formats 
on a Display” on page 3-10 and “Clearing a Specified Number of Lines” on 

page 3-13. 


In the following example, the fields are defined for a record format as follows: 
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e Fields from record format A occupy lines 1 through 4. 

e Fields from record format B occupy lines 5 through 7. 

e Fields from record format C occupy lines 8 through 10. 

e Fields from record format D, which has the CLRL keyword specified for it, 
occupy lines 5 through 9. 


In the following illustration, record formats A, B, and C are displayed first. When 
record format D is displayed, it replaces record formats B and C. 


Lines 
1 
2 
Record Format A 
i ac aaa 
6 Record Format B 
Po Wee testes ee eee Pe A eat eae eee ce hese my Atk ek ete ae a ee te eel 
8 
9 Record Format C 
HOY. UU eae ee Ft oe Ng a tet ae oye ee ee Rr Me hate te ae ek a te Fe | 
11 
12 
t Record format D is displayed 
Lines 
1 
2 
; Record Format A 
Bn RO a ace ey 
6 
7 
8 Record Format D 
Weipa eg es Sea Sec een ert Ne sepa re pe ag tes we a teers ace 
10 
11 
12 
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Figure 3-3. Replacing Record Formats 


If record format D did not have the OVERLAY keyword specified for it, the following 
would have happened in the previous example: 


e Record format A would also have been deleted. 

e Lines 5 through 7 of record format B would have remained on the display. The 
data in any fields of record format B overlaid by record format D would have 
been changed. (see “Clearing a Specified Number of Lines” on page 3-13 for 
more information). 


Deciding the Order of Record Formats Written to the Display 
To improve performance, records containing input fields should be sent to the 
display station in the order in which they appear on the display. 


In Figure 3-3, if record formats A and B both contain input fields and appear on the 
same display, record format A should be sent to the display first. 
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Overlaying and Erasing Record Formats on a Display 

To avoid erasing the existing display when your program displays a new record 
format for output or to allow input, you can specify the OVERLAY keyword. The 
OVERLAY keyword causes only those records that are completely or partially over- 
lapping to be erased; all other records remain on the display. 


Note: The OVERLAY keyword does not prevent the screen from being erased if it 
is in effect for the first write operation after a file is opened unless the DDS 
keyword ASSUME is specified for any record format in the display file. 


You can use the OVERLAY keyword to display information from your application 
that needs to be presented together but naturally falls into two or more pieces. For 
example, you could use one record format in your application to present information 
for a state at the top of a display and another record format to provide the informa- 
tion for a particular region within that state. 


To place two or more records on the display at the same time, separate the write 
operations for your display from the read operations. Then, when you perform 
each write operation, the system takes the data from the record that you have pro- 
vided it, combines it with the information specified in the record format, and places 
it on the display. You can lock the keyboard until the display is ready to perform 
the read operations by doing one of the following: 


¢ Specify the LOCK keyword on all the record formats 
¢ Specify *YES for the Defer Write (DFRWRT) parameter for the display file 


You can use multiple record formats when you want to present lists of information 
in a subfile to the user. A subfile is a group of records that have the same record 
format and are read from and written to a display station in one operation. For 
more information about subfiles, see Chapter 4, “Displaying Groups of Records 
Using Subfiles” on page 4-1. 


To erase certain records from the display when you overlay records, use the 
ERASE keyword with the OVERLAY keyword. The following diagram shows the 
effect of the OVERLAY and ERASE keywords on an output operation: 


Before 1 After 
A A 
Put D 
with OVERLAY D 
B > 
Not Used 
Cc C 
Put D A 
with OVERLAY 
and ERASE C D 
> 
Not Used 
\ 


RV2W032-1 
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Record format B is erased because record format D overlaps it, and record 
format D is displayed. Record format D did not use all of the space record 
format B previously used so it does not overlap record format C. 


1 Record format B is erased because record format D overlaps it and record 
format C is erased because ERASE C is specified. Record format D is dis- 
played, and part of the display is no longer in use. 


Starting Your Record Format on a Specific Line 
To start your record format on a specific line, use the starting line number (SLNO) 
keyword. On the SLNO keyword, you can specify one of the following: 


e The actual starting line number for the record format (a value from 1 to 27). 
When you specify an actual line number, the system adjusts the line numbers 
for all fields in a record by the specified value minus 1. 

¢ A variable starting line number (*VAR), which allows you to specify a starting 
line number value in your high-level language program at run time. Depending 
on the value specified in your program, the following occurs: 


Table 3-3. Results of SLNO(*VAR) Values 


Value Specified Results 
0 or no value specified A starting line number of 1 is assumed. 
Value exceeds the number The system sends a message to the program and the I/O 


of lines on the screen or is a request is not performed. 
negative value 


The starting location for the A warning message (severity 10) is issued at file creation 
field for at least one display time. At run time, an error message is issued if the screen 
size is row 1, column 1 size being displayed contains a field starting in row 1, 


column 1, and the variable starting line number is set to 1 
by the program. 


Each programming language provides a different way to set and add to the starting 
line number. See the appropriate manual for the language you are using. 


The system adjusts the line numbers for each field in the record format by the 
specified value minus 1. If the resulting line number exceeds the screen size, the 
field is not displayed. In addition, if any part of a field goes beyond the last line on 
the screen, the field is not displayed. 


The SLNO keyword cannot be used in a record format that contains the record- 
level keywords ASSUME, KEEP, USRDFN, SFL, or SFLCTL, or in a display file 
that contains the file level keyword PASSRCD. 


However, the SLNO keyword may be used with several other DDS keywords: 


e lf the CLRL keyword is used with the SLNO keyword and the CLRL keyword 
specifies a number of lines to clear, clearing starts with the starting line number 
on the SLNO keyword. 


e If you use the SLNO(*VAR) keyword with the OVERLAY keyword but without 
the CLRL keyword and then write the record several times, each time with a 
different starting line number, the previous record is deleted before the new 
record is displayed. 
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e If the SLNO keyword is used with the PUTOVR, PUTRETAIN, ERRMSG, or 
ERRMSGID keyword in effect, the system checks the starting line number to 
determine if the previous output operation to the record had the same starting 
line number: 


— lf the starting line number is the same, the action specified by the 
PUTOVR, PUTRETAIN, ERRMSG, or ERRMSGID keyword is performed. 

— If the starting line numbers are not the same, the PUTOVR, PUTRETAIN, 
ERRMSG, or ERRMSGID keyword is ignored, and the record format is dis- 
played with the lines adjusted by the new value. 


The following DDS shows an example of using the SLNO(*VAR) keyword: 


| deePivvedesietyes eles Pane i3e ce PeeecBiicd hac Beene bins sOse26 bene sd eee 


A R ORDENT 

A 1 36'ORDER ENTRY' 

A 3. 2'Enter customer number: ' 
A CUST 5 B +2 

A 5 2'Enter order number: ' 
A ORDNBR 6 6B +2 

A 7 2'ITEM NUMBER' 

A 7 18'DESCRIPTION' 

A 7 44'QUANTITY' 

A R LINITM OVERLAY 

A SLNO(*VAR) 

A CLRL(*NO) 

A ITEM 6 00 9 2 

A DESCRP 20 O 9 18 

A QTYORD 3 00 9 44 

A R INPFMT OVERLAY 

A 23 2'Enter item number: ' 
A ITMNBR 6 OI +2 

A +5'Enter Qty:' 

A QTY 3 Ol +2 


Figure 3-4. Sample DDS Source Showing Use of the SLNO(*VAR) Keyword 


In this example, the record format ORDENT contains the prompt for an Order Entry 
display. When the user enters a customer number and an order number, the fol- 
lowing occurs: 


1. The program writes the record format INPFMT to the display, which allows the 
user to enter an item number and quantity ordered. 


2. After the user enters the item number and the quantity, the program retrieves 
the description of the item from a file and writes the record format LINITM to 
the display. 


3. The program writes the INPFMT record format to the display to allow the user 
to enter another item number. 


The design of this display allows the user to enter the item number and quantity on 
the same line. As a line item is entered, the program uses the LINITM record 
format to build the order on the display. The SLNO(*VAR) keyword is used so the 
program can add a line to the display each time the LINITM record format is 
written. The CLRL(*NO) keyword has to be specified on the LINITM record format 
so that the previous record is not deleted when a new record is written. 
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When the LINITM record format is first written to the display, the value of *VAR is 1 
so the fields are displayed on line 9. On each successive output operation to this 
record format, the program adds 1 to the starting line number so that a new line 
item is added to the display. 


After the user enters two item numbers and quantities, the display looks like this: 


(— rah 
ORDER ENTRY 
Enter customer number: 34785 
Enter order number: 1J2340 
ITEM NUMBER DESCRIPTION QUANTITY 
96321 Pliers 115 
86768 Saws 125 
Enter item number: __ Enter Qty: 
— ae 


The SLNO keyword is most efficient when you want the user to always enter data 
on the same line and yet build a display of previously entered records, as shown in 
the preceding example. However, for a typical inquiry function where you want to 
display more than one record at a time, the use of a subfile is more efficient. 


Clearing a Specified Number of Lines 

To clear a certain number of lines on the screen before you write a record format to 
the screen, use the clear lines (CLRL) keyword. You can specify the CLRL 
keyword even when the record contains no fields that are displayed. Clearing 
begins with the starting line number, and the value specified on the CLRL keyword 
determines the number of lines to be cleared (any value from 1 to 27). The starting 
line number is determined as follows: 


e If the SLNO keyword is not specified, the field locations determine the starting 
line number. 

¢ If the SLNO(nn) keyword is specified, nn is the starting line number. 

e If the SLNO(*VAR) keyword is specified, the starting line number defaults to 1 
at the time the display file is created and can be changed by the application 
program at the time it is run. 


You can also specify the following values to clear specific lines: 
Value Lines Cleared 


*END All lines from the starting line to the end of the display 


*NO Only the lines of the display that are used by the overlapping record 
format 
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*ALL All lines of the display. Since the default action is to clear all the lines of 
the screen, you do not normally have to specify CLRL(*ALL) unless you 
also specify a DDS keyword, such as USRDSPMGT, that changes this 
default. 


Note: When you use the CLRL keyword, you should specify *YES for the 
RSTDSP parameter on the CRTDSPF or CHGDSPF command; otherwise, 
data on the display may be lost if the file is suspended. 


You can use the CLRL(*NO) keyword to prevent an overlapped record from being 
deleted when the overlapping record is written to the display. If you use this 
keyword, any records being displayed that are to be overlapped are not deleted 
from the screen; the new record overlays them entirely or partially. There is a per- 
formance advantage to using CLRL(*NO) if you have a display that contains con- 
stants and data that is repeatedly sent to the screen. By sending the constants as 
a separate format and by using CLRL(*NO) for the format containing only the data, 
you can reduce the time required to send the record format to the display. For 


example: 
Lines 
1 
2 
i Record Format A (lines 1 through 4) 
2 Record Format B (lines 5 through 8) 
: Record Format C (lines 7 through 12) 
I ce ee 
10 
1 i a a tg 
12 
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If CLRL(*NO) is specified on record format C, all fields of record format B not over- 
lapped by C remain on the screen when record format C is written to the screen. If 
the OVERLAY or PUTOVR keyword were used for this same situation, record 
format B would be deleted when record format C is written to the screen because 
record format C overlaps record format B. 


The following considerations apply to the CLRL keyword when used with other DDS 
keywords: 


e If the CLRL keyword is specified in a record format with input-capable fields, 
any input-capable fields in the overlapped records are no longer input-capable. 
Fields in all other record formats that are not overlapped remain input-capable. 
If you do not want these fields to remain input-capable, you should use the 
PROTECT keyword on the record format along with the CLRL(nn) keyword. 


e Records with the CLRL keyword and with no input-capable fields are assumed 
to be at line 0. Thus, if the CLRL(nn) keyword is specified in a record format 
that has no input-capable fields, all records already on the display remain on 
the display and their input-capable fields remain input-capable. Because 
records that start at line 0 are not known to the system, the ROLLUP and 
ROLLDOWN keywords do not work for these records. Also, these records may 
not be cleared completely when they are overlapped by other records that have 
the OVERLAY keyword specified. The lines needed for the overlapping record 
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are cleared whereas the lines not needed for the overlapping record remain on 
the screen. 


e¢ The CLRL(nn) keyword is not allowed in a record format with the record-level 
keywords ASSUME, KEEP, USRDFN, SFL, or SFLCTL, or in a display file with 
the file level Keyword PASSRCD. 


¢ The CLRL(nn) keyword is ignored if either the ERRMSG or ERRMSGID 
keyword is in effect. 


e If the CLRL(nn) keyword is used and the PUTOVR or PUTRETAIN keyword is 
in effect, the clearing of lines may conflict with the PUTOVR or PUTRETAIN 
function. The PUTOVR or PUTRETAIN keyword requires that the fields being 
overridden be on the display whereas the CLRL(nn) keyword may clear those 
fields first. If a record becomes unavailable for input because of the CLRL(nn) 
keyword, the input-capable fields remain input-capable if the PUTOVR keyword 
is in effect. However, the system issues a message if the program attempts to 
read such a record. Although the CLRL(nn), CLRL(*NO), and CLRL(*END) 
keywords imply the OVERLAY keyword, the following example illustrates the 
differences between the CLRL and OVERLAY keywords: 


ear ee ee Ph Pa eR ee eg oe, eer me Peon. meen See 


A R RECORD1 

A FLD1 10 I 4 5 

A FLD2 10 I 5 5 

A 5 21'Enter employee number' 
A R RECORD2A OVERLAY 

A FLD3 1 B5 2 

A 6 2'Required field' 

A 7 2'Enter 1, 2, or N' 
A FLD4 19 0 8 2 

A R RECORD2B CLRL(4) 

A FLD5 1 B5 2 

A 6 2'Required field' 

A 7 2'Enter 1, 2, or N' 
A FLD6 19 0 8 2 

A R RECORD3 OVERLAY 

A FLD7 10 O 815 

A 

A 

A ‘ . 

A FLD8 10 Bil2 4 

A R RECORD4 CLRL(*NO) 

A FLD9 42 111 2 


Figure 3-5. Sample DDS Source Showing Difference between CLRL and OVERLAY 


The following results occur if the program performs the output operations on the 
record format in the following order: 
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Table 3-4. Results from CLRL Example 


Order of Record 


Formats Results 

RECORD1 Lines 4 through 12 are deleted when RECORD2A is written to the 
RECORD3 display because RECORD2A overlaps RECORD1 and RECORDS, 
RECORD2A and only the OVERLAY keyword is specified for RECORD2A. 
RECORD1 Lines 5 through 8 are cleared before RECORD2B is written to the 
RECORD3 display because the CLRL(4) keyword is specified. FLD1 in 
RECORD2B RECORD?1 and any input-capable fields in RECORDS (lines 9 


through 12) remain on the screen but are no longer input-capable 
because part of RECORD1 and RECORDS is overlapped by 


RECORD2B. 
RECORD1 RECORD1 remains on the screen when RECORDS is written to the 
RECORD3 screen because the OVERLAY keyword is specified in RECORDS. 
RECORD4 When RECORD4 is written to the screen, it uses part of line 11, 
RECORD2A which is also used by RECORD3, and because CLRL(*NO) is 


specified in RECORD4, RECORDS remains on the screen. 
However, the system is no longer aware that RECORDS is on the 
screen so when RECORDAA is written, only lines 4 through 8 are 
cleared; the part of RECORD3 below line 8 remains on the screen. 


Rolling Data between Two Lines on a Display 

If you are using a high-level language program, you can roll the data between two 
lines on the display up or down by specifying the allow roll (ALWROL) keyword. 
The lines vacated by the rolled data are set to nulls and another record format can 
be written to those lines. 


In your program, you must specify the following: 


e The starting line number and the ending line number of the lines to be rolled. 
The start and end line numbers define a window on the screen. 


e The number of lines to be rolled. \f the number of lines to be rolled is positive, 
the data is rolled up. If the number of lines to be rolled is negative, the data is 
rolled down. 


¢ Whether the roll is to be up or down. 


In the window, the lines of data are rolled up (or down) by the number of lines you 
specified in your program. The data rolled off the window is gone. The input- 
capable fields of any record format partially or completely within the window are no 
longer input-capable. After the roll, your program cannot issue an input operation 
to any record format within the window. 


The following example shows a display before a program-controlled roll occurs, and 
the same display after a program-controlled roll occurs. The following is specified 
in the program: 


e The starting line number is 8 
e The ending line number is 18 
e¢ The number of lines to be rolled down is 6. 
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Display before the Roll Operation 


UPDATE CUSTOMER ORDER RECORD Line 1 
To end this program, press CF1 Line 3 
Record 
format 
; 1 
Enter your operator number. Line 8 
Enter customer number. Line 10 
Press CF3 to display option menu Line 12 
RSLH165-0 


Display after the Roll Down Operation 


UPDATE CUSTOMER ORDER RECO RD Line 1 


Unchanged 
To end this program, pressCF1 Line 3 


Item numberordered: ——___ Line 9 | Record 
format 
Quantity ordered: Line 11 J 2 
Enter youroperatornumber: 25 Line 14 
Enter customernumber: 12345 ; 
Line 16 
Press CF3 to display option menu | 
) Line 18 
Previous 
lines 8 
through 12 
after being 
rolled down 


RSLH171-0 


The ALWROL keyword cannot be used with the file level keyword PASSRCD or 
with the following record-level keywords: KEEP, ASSUME, USRDFN, SFL, or 
SFLCTL. 


If the ERRMSG, ERRMSGID, PUTOVR, or PUTRETAIN keyword is in effect for the 
same output operation in which the ALWROL keyword is in effect, the system 
issues message CPF5014. If an ERRMSG, ERRMSGID, PUTOVR, or record level 
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PUTRETAIN keyword is not in effect, the message is not issued. However, if the 
PUTRETAIN keyword is specified at the field level with option indicators, the 
message (CPF5014) is issued if the option indicators for the PUTRETAIN keyword 
are on or off. 


Overriding the Attributes or the Content of a Field 
To send only some of the data and attributes of a record to the display, use the 
following keywords: 


e Put with explicit override (PUTOVR) 
¢ Override data (OVRDTA) 
¢ Override attribute (OVRATR) 


By sending less data or attributes, you can shorten the response time at the 
display, especially for remotely attached displays. 


When the PUTOVR keyword is specified, the following occurs: 


¢ The display attributes are overridden for those fields with the OVRATR keyword 
in effect. 

¢ The data content is overridden for those fields with the OVRDTA keyword in 
effect. 

¢ The output operation functions as if the OVERLAY keyword were also in effect, 
even if the OVERLAY keyword is not specified. 


The PUTOVR keyword cannot be specified in a record format that contains the 
PUTRETAIN keyword nor can it be used for subfile records. 


The display attributes that can be overridden by the OVRATR keyword are: 


CHECK(ER) End of Record 
CHECK(ME) Mandatory enter 
DSPATR(MDT) Set on modified data tag 
DSPATR(PR) Protect 
DSPATR(BL) Blink 
DSPATR(CS) Column separator 
DSPATR(HI) High intensity 
DSPATR(ND) Nondisplay 
DSPATR(PC) Position cursor 
DSPATR(RI) Reverse image 
DSPATR(UL) Underline 

DUP Dup key capable 


The following is an example of the PUTOVR keyword. 
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A R ITMRVW 

A PUTOVR 

A 1 35'ITEM REVIEW' 

A 3  2'Item number: ' 

A ITMNBR 5 B +2 

A 5 2'Item description:' 
A ITMDSC 20 +2 

A 10 OVRDTA 

A 7 2'Item price:' 

A ITMPRC 8 2 +2 

A 15 OVRDTA 

A 9 2'Warehouse location: ' 
A WHSLOC 3 +2 

A 20 OVRDTA 

A 11 2'Quantity on hand:' 
A QTYOH 5 0 +2 

A 25 OVRDTA 

A OVRATR 

A N25 30 DSPATR(HI) 


Figure 3-6. Sample DDS Source Showing Use of the PUTOVR Keyword 


The DDS describes a display that allows the user to enter an item number, and to 
review the item description, the item price, the warehouse location, and the quantity 
on hand: 


1. On the first output operation, all fields are sent to the display, and all option 
indicators are off. The PUTOVR keyword is ignored because the record is not 
already on the screen. On the first output operation, the current field values in 
the program are displayed for the output fields. If your program has not set 
any of these fields, the values will be whatever the high-level language used to 
initialize the output buffer. 


If an output-capable field must always have a specific value on the first output 
operation, you can use the DFT or DFTVAL keywords to initialize the field to 
that value. When used on an output-capable field with the PUTOVR and 
OVRDTA keywords the DFT keyword causes the system to place the default 
value rather than the program value on the display when the record is first 
placed on the display. 


2. The user enters an item number. The program sets on indicators 10, 15, 20, 
and 25 and issues a write-read operation to display the output fields. On the 
write operation, the PUTOVR keyword is in effect because the record is already 
on the screen. Because the OVRDTA keyword is specified on the ITMDSC, 
ITMPRC, WHSLOC, and QTYOH fields and because their option indicators are 
on, these fields are the only data sent to the display. 


If the user enters another item number and the data for a field already dis- 
played does not change, the program sets off the option indicator and does not 
display that field again. For example, assume that for the second item number, 
the WHSLOC is the same as for the first item number. On the output operation 
to display the information for the second item number, the program sets off 
indicator 20. Therefore, the only fields sent to the display are ITMDSC, 
ITMPRC, and QTYOH because indicators 10, 15, and 25 are on. 
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For the QTYOH field, the program can change the attributes for the field without 
changing the data by setting off indicator 25 and setting on indicator 30 before the 
output operation. 


You can use the option indicators on the OVRDTA keyword to control which fields 
are sent to the display. If no option indicators are used, all fields with the OVRDTA 
keyword specified are sent to the display on each output operation because the 
OVRDTA keyword is in effect when the PUTOVR keyword is in effect. In the pre- 
ceding example, if no option indicators were used, all four fields would be sent to 
the display on each output operation. You can also use the same indicator to 
control more than one field. 


An alternative design for this same application is to use two record formats and 
send the constants to the display in one record format and the variables in the 
other record format. You would have to use the CLRL(*NO) keyword to prevent the 
record format containing the constants from being erased. However, if the record 
format is already on the display, the use of the PUTOVR keyword provides the 
most efficient approach. 


The following examples illustrate how to use the PUTOVR keyword for efficient 
coding: 


[sere Peiees Tete Peso eee eoea aha ne cote eB ata on ca eeeteee sl acd 
R PROMPT 
CFO3(91 'Return') 
PUTOVR 
ERASEINP 
OVERLAY 
28'Efficient Coding Example' 
2'FLD1' 
7 
2'FLD2' 
7 
OVRDTA 
7 2'FLD3' 
FLD3 5 7 7 
15 OVRDTA 
9 2'FLD4' 
FLD4 5 9 7 
OVRDTA 
16 DSPATR(HI) 
11 2'FLD5' 
FLD5 5 11 7DFT('ABCDE') 
OVRDTA 
17 DSPATR(HI) 
13. 2'Constant 1' 
OVRATR 
18 DSPATR(BL) 
15 2'Constant 2' 
OVRATR 
N19 DSPATR(ND) 
17. 2'Constant 3' 
20 OVRATR DSPATR(RI) 


FLD1 5 I 


mow Wr 


FLD2 5 


rFPrrrrrrrrrrrrrrrrrrrrrrrrrrrrsTE 


Figure 3-7. Sample DDS Source Showing Efficient Use of PUTOVR Keyword 
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In the preceding example, the following happens: 


1. If the record format is not currently on the display, the PUTOVR, OVRATR, and 
OVRDTA keywords are ignored when the record format is displayed. On sub- 
sequent output operations when the record format is already on the display and 
the PUTOVR keyword is in effect, only the fields or constants defined with the 
OVRATR or OVRDTA keyword are sent to the display. The ERASEINP 
keyword is used because it is the most efficient way to clear all input fields, and 
the OVERLAY keyword is used because it is required with the ERASEINP 
keyword. 


2. FLD1 is an input field that is cleared each time the record format is displayed. 


3. FLD2 is sent to the display each time the record format is displayed because 
its associated OVRDTA keyword is unconditionally specified. 


4. FLD3 is sent to the display on the first output operation. On subsequent output 
operations, FLD3 is not sent to the display unless indicator 15, which is used to 
condition the OVRDTA keyword, is on. 


5. FLD4 is sent to the display on each output operation because its associated 
OVRDTA keyword is unconditionally specified. When the OVRDTA keyword is 
in effect, the attributes for the field are always sent to the display. Indicator 16 
is used to control the DSPATR(HI) keyword for FLD4. 


6. On the first output operation, the default value of ABCDE appears in FLD5. On 
subsequent output operations, a value from the program is displayed in FLD5 
because its associated OVRDTA keyword is unconditionally specified. 

Indicator 17 is used to control the DSPATR(HI) keyword for FLD5. 


7. Constant 1 is always displayed, but it is only sent to the display on the first 
output operation. However, the attributes for the field are sent to the display 
each time the record format is written, and option indicator 18 is used to control 
whether the field blinks. 


8. Constant 2 is sent to the display only on the first output operation. However, 
the attributes for the field are sent to the display each time the record format is 
written, and if option indicator 19 is off, Constant 2 will not be displayed. 


9. Constant 3 is sent to the display only on the first output operation. However, 
the attributes for this field are not sent to the display on subsequent output 
operations unless indicator 20 is on. If option indicator 20 is on when an output 
operation is done, Constant 3 is displayed in reverse image, and it will continue 
to appear in reverse image regardless of the status of indicator 20 on subse- 
quent output operations. 


The following example shows how the PUTOVR keyword can be used for an appli- 
cation in which the user enters some information common to a group of records 
and then repeatedly enters detailed information relating to specific records in the 


group. 
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| ae¥sie ees ees slecs i teew beds phe an Alero ecebyecohiecs8 seta sed ess 
R HEADING TEXT('Header Display') 
SETOF(88 'ERASEINP CTL') 
CFO3(91 'Return') 
1 2'HEADING INFORMATION' 
DSPATR(HI) 
1 60'CF3-End of Program' 
2 60'CF2-New heading' 


HDING 5 I +2 
R DETAIL TEXT('Detail display') 
OVERLAY 
PUTOVR 
PROTECT 
88 ERASEINP 


CFO2(92 'New header’) 
8 2'DETAIL DISPLAY' 


rPrrrrrrrrrrrrrrrrrrrstsy 


DSPATR(HI) 
10 2'Input' 
FLDA 5 I +2 
12 2'Output' 
FLDB 5 +2DFT(' ') 
OVRDTA 


Figure 3-8. Sample DDS Source Showing Another Use of PUTOVR Keyword 


In the preceding example, the following happens: 


1. The program displays the HEADING record format, and then performs an input 
operation to the record format to receive the HDING field as input. The SETOF 
keyword in the HEADING record format sets off indicator 88, which is used to 
condition the ERASEINP keyword in the DETAIL record format. 


2. The program then displays the DETAIL record format. Because the OVERLAY 
keyword is in effect, the HEADING record format remains on the display. The 
PROTECT keyword is also in effect so the input field (HDING) in the HEADING 
record format is protected. Therefore, the user cannot change this field when 
the DETAIL record format is displayed. 


3. The ERASEINP keyword is conditioned by option indicator 88. Because indi- 
cator 88 is off the first time the DETAIL record format is displayed, the 
ERASEINP keyword is not in effect. On subsequent output operations, indi- 
cator 88 is set on and the ERASEINP keyword is in effect. Therefore, FLDA is 
cleared on subsequent output operations. The option indicator is used on the 
ERASEINP keyword so that it is not in effect the first time the DETAIL record 
format is displayed. Because the ERASEINP keyword is processed before the 
PROTECT keyword, it would clear the HDING field in the HEADING record 
format if it were in effect the first time the DETAIL record format is written. 


4. FLDB is an output field that is sent to the display on each output operation 
because the OVRDTA keyword is specified unconditionally. The DFT keyword 
with a value of blanks is used so the field will not contain any data the first time 
the DETAIL record is displayed for a group. 
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Erasing All Unprotected Input and Output/Input Fields on the 
Display 

To erase all unprotected input-capable fields, use the erase input (ERASEINP) 
keyword. The ERASEINP keyword can only be used with the OVERLAY keyword. 


To erase all unprotected input-capable fields that have their modified data tags on, 
specify *MDTON for the ERASEINP keyword. To erase all unprotected input- 
capable fields whether their modified data tags are on or not, specify “ALL for the 
ERASEINP keyword. 


The ERASEINP keyword can improve response time because it clears fields rather 
than sends blanks to the display. If the fields erased at the display do not have 
their modified data tags set on for the next read operation, data is returned for 
those fields from the input save area. This is data saved by the system from the 
previous return of the field from the display station. 


You can use the INZINP keyword at the record level with ERASEINP(*ALL) and 
PUTOVR to initialize the input save area without sending data for the cleared fields 
to the display. 


Resetting Modified Data Tags Associated with Records on the 
Display 

To reset the modified data tags, use the modified data tag off (MDTOFF) keyword. 
The MDTOFF keyword, which can only be used with the OVERLAY keyword, is 
processed before the next record is displayed. 


To reset only the modified data tags of the unprotected fields, specify “UNPR for 
the MDTOFF keyword. To reset the modified data tags of all input-capable fields, 
specify “ALL for the MDTOFF keyword. 


Keeping a Record or Field on a Display 

The PUTRETAIN keyword is used to reduce the number of characters sent to the 
display. This keyword can only be used with the OVERLAY keyword and can be 
used to change only the display attributes of a field. Except for not sending data, 
all other functions are supported when the PUTRETAIN keyword is specified. 


Using the PUTRETAIN keyword at either the record format level or the field level 
can cause fields from this record which were previously written to the display to 
remain on the display even if they are not selected for this write operation. To 
avoid this, you can use the PUTRETAIN keyword at the field level and define the 
field twice: once with option indicators as you want it to appear in the display, and 
once with no option indicators and as a constant with a value of blanks. If the first 
field is not selected, the second field is. The second field is displayed so the 
blanks erase the contents of the field that is not selected. 


Note: The ERRMSG and ERRMSGID keywords function as if the PUTRETAIN 
keyword were specified at the record format level. That is, no fields are 
sent to the display, no field attributes for other fields are changed, and no 
command keys are changed when the ERRMSG and ERRMSGID keywords 
are in effect. 


The following is an example of the PUTRETAIN keyword used at the record format 
level. The following DDS describes a student search menu having three options. 
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The option selected is highlighted. For example, if option 1 is selected, the char- 
acter string 7. By number is highlighted. 


| cues eve ine yw Hees eQeae Pink sSevieebewec4e cas binesSecas tees Odeaetes esl ess 


A R SELECT OVERLAY 

A PUTRETAIN ERASEINP 

A N44 1 2'STUDENT SEARCH MENU' 
A N44 3 10'1. By number' 

A 10 DSPATR(HI) 

A N44 4 10'2. By name' 

A ll DSPATR(HI) 

A N44 5 10'3. By address' 

A 12 DSPATR(HI) 

A N44 10 2'Select the number of the item to + 
A search by:' 

A INPUT 1 110 47 

A 44 DSPATR(RI) 


Figure 3-9. Sample DDS Source Showing Use of the PUTRETAIN Keyword 


The following happens: 


1. On the first output operation, all fields are sent to the display, and all option 
indicators are off. The PUTRETAIN keyword is ignored because the record is 
not already on the display. 


2. The user selects item 1, 2, or 3. When the program receives the input, it sets 
on indicator 10, 11, or 12, depending on which item is chosen. If anything 
other than item 1, 2, or 3 is chosen, the program sets on indicator 44. 


On the next output operation, field 1, 2, or 3 is highlighted, or the input field is 
in reverse image, depending on which indicator is on. 


The data for all fields is not resent to the display but the field attributes are 
resent. No data is sent for constants. To resend attributes for each output 
field or constant, 4 bytes are needed. To resend attributes for each input- 
capable field, 9 bytes are needed. By using the PUTRETAIN keyword, you 
reduce the number of characters sent to the display by 96, from 138 to 42. 
(These numbers do not include protocol control characters needed to frame 
data.) 


The ERASEINP keyword causes the user’s selection to be erased. 


The following is an example of the PUTRETAIN keyword used at the field level. 
Here, the PUTRETAIN keyword is used to keep input that is not valid and to reduce 
the number of characters sent to the display. The following DDS describes a 
display containing an item’s name, color, shape, and size, and asks for quantity. 
The user can change the values for color, shape, and size. 
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A R CHANGE OVERLAY 

A 1 2'CHANGE MENU' 

A N43 3 2'Change the underlined fields to 
A change the description. ' 
A 4 2'Item:' 

A ITEM 20 O 412 

A 44 PUTRETAIN 

A 5 2'Quantity:' 

A QTY 4Y OI 5 12 

A 44 PUTRETAIN 

A 09 DSPATR(BL PC) 

A 6 2'Color:' 

A COLOR 10 B 6 12 

A 44 PUTRETAIN 

A 10 DSPATR(BL PC) 

A 7 2'Shape:' 

A SHAPE 10 B 7 12 

A 44 PUTRETAIN 

A ll DSPATR(BL PC) 

A 8 2'Size:' 

A SIZE 10 B 8 12 

A 44 PUTRETAIN 

A 12 DSPATR(BL PC) 

A 44 9 2'Choice:' 

A 44 CHOICE 20 O 9 12 

A 15 9 12' : 


Figure 3-10. Sample DDS Source Showing Use of the PUTRETAIN Keyword 


The following happens: 


1. On the first output operation, all indicators are off, so all the constants and the 
fields except CHOICE and the constant field following CHOICE are sent to the 
display. 


2. The user enters a quantity. The program sets on indicator 43. When the next 
output operation occurs, indicator 43 prevents the second constant field from 
being resent. 


3. When the user is to enter the quantity for another item, the program issues 
another output operation. The attributes for the fields QTY, ITEM, COLOR, 
SHAPE, and SIZE are sent to the display. Field selection prevents the 
CHOICE field from being sent to the display. 


At least one field, in this case QTY, must be kept to prevent the entire record 
area from being erased. 


4. If the user enters a quantity, color, shape, or size that is not valid, indicator 44 
is set on so that the input fields (QTY, COLOR, SHAPE, and SIZE) are not 
erased and so that the output field CHOICE is sent to the display. In addition, 
the appropriate indicator, 9, 10, 11, or 12, is set on so that the input field in 
error blinks and the cursor position is below the field. (The CHOICE field would 
show the user valid choices for the field in error.) 


5. The CHOICE field and a constant field of blanks are defined for the same 
location. After the user enters valid data, indicator 15 is set on, indicator 44 is 
set off, and the constant field initializes the CHOICE field to all blanks. 
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Deferring the Write Operation Until a Read Request is Made 
The DFRWRT parameter on the Create Display File (CRTDSPF) or Change 
Display File (CHGDSPF) command allows you to specify how the system is to 
handle write operations. If you specify DFRWRT(*NO), the program does not 
regain control until the write operation has displayed the data and updated the 
input/output feedback area. 


If you specify the default of DFRWRT(*YES) for the file, the program regains 
control after the output record is processed. The program can then use the record 
area where the output was stored to start processing the next write or write-read 
operation. The data is actually sent to the display only when a read or write-read 
operation is issued or when the FRCDTA DDS keyword is in effect for a write-only 
operation. 


Using DFRWRT(*YES) on a display file improves systems performance; however, 
DFRWRT(*YES) should not be used in the following circumstances: 


e If you want to find out immediately if the write operation was successful. An 
error associated with a write operation for a file with DFRWRT(*YES) specified 
is issued only when the data is actually sent to the display. 


e lf the time between the write operation and the read or write-read is long. For 
example, if the program does several database operations after the write oper- 
ation (before it issues a read or write-read operation), the user will not see the 
data while the database operations are performed. 


e If the file is closed after the write-only operation and the KEEP keyword is not 
specified. If the display file has the DDS keyword KEEP specified in any of its 
records, the data accumulated from the write-only operation is displayed when 
the file is closed. However, if the KEEP keyword is not specified, the data may 
never be displayed. 


The DFRWRT parameter has no effect on the following: 


e Write operations using user-defined data streams 
e Write operations to display files that use program-described data 
e Record formats for which the FRCDTA DDS keyword is in effect 


Specifying Default Values for Fields 

Both DFT and DFTVAL keywords are used to specify the default values to be dis- 
played for fields. However, there are differences between the way the two are 
used. 


The DFT keyword can be used with constant, input, output, and output/input fields 
and cannot be optioned. When it is used with output or output/input fields the 
OVRDTA and PUTOVR keywords must also be specified. If the record is not on 
the display, this combination of keywords will cause the default value to be placed 
on the screen. If the record is already on the display, the PUTOVR keyword is in 
effect and the data from the program appears on the display rather than the default 
value. 


The DFTVAL keyword can be used only on output and output/input fields and can 
be optioned. If it is in effect on an output operation, the value from the keyword is 
placed in the field, rather than the value from the program. If the record is on the 
display and the PUTOVR and OVRDTA keywords are in effect, the program value 
is used rather than the default value. 
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The DFT and DFTVAL keywords may not be specified on the same field. 


Indicating Which Mode to Display Records 

Some display stations, for example the 3180-2 display station, support an alternate 
screen size. You can specify this alternate size using the DSPMOD keyword. The 
DSPMOD keyword indicates, for a particular record, which mode is used to display 
the record. Any record that does not have the DSPMOD keyword specified for it is 
displayed in the default display mode. The default display mode is the first of the 
“DS3 or *DS4 display sizes on the DSPSIZ keyword. 


The DSPMOD keyword is only valid when both *DS3 and *DS4 are specified on the 
DSPSIZ keyword. This keyword is valid only at the record level. Option indicators 
are allowed. The DSPMOD keyword may not be duplicated in a record. 


Note: The capability to display in 27 by 132 mode is allowed on 3180-2, 3197, 
3477 Models FA, FC, FD, FE, FG, FW, and 3487 Models HE, HD, HW, HC 
display stations attached to a local display station controller, or remotely 
attached to a 5294 or 5394 controller. The DSPMOD keyword is ignored 
unless these controllers are used. 


For example, the following DDS would display RECORD1 in 27 by 132 mode, and 
RECORD2 in 24 by 80 mode (the default mode set up by the DSPSIZ keyword). 
RECORDS will be displayed in 27 by 132 mode if option indicator 03 is on, or in 24 
by 80 mode if option indicator 03 is not on. 


Pee eee Gee reer Sener, er ee, ee ne ee ee een eee, ereeey Jes 


A DSPSIZ(*DS3 *DS4) 
A R RECORD1 DSPMOD(*DS4) 

A R RECORD2 

A R RECORD3 

A 03 DSPMOD(*DS4) 


Figure 3-11. Sample DDS Source Showing Use of the DSPMOD Keyword 


The use of the DSPMOD keyword can cause the display mode to be changed dra- 
matically. Caution should be used when specifying the DSPMOD keyword. When 
a record with DSPMOD active causes the mode to be changed, all records cur- 
rently on the display are cleared and deleted from the active record table. The 
record with DSPMOD active is then sent to the display. The mode for this record is 
maintained on the display as long as the DSPMOD keyword is active. Setting 
DSPMOD off or a write operation to another record without DSPMOD causes the 
display mode to be placed back in the primary display screen size for the display 
station. 


Using the previous sample DDS source, the DSPMOD keyword gives the following 
results if records are written to the screen in the following order: 


e RECORD1 is displayed in *DS4 mode. 

e The display screen is cleared and RECORD2 is displayed in *DS3 mode. 

e If indicator 03 is off, RECORDS is displayed in ~DS3 mode. RECORD2 
remains on the display if the OVERLAY keyword is specified. 

e If indicator 03 is on, RECORD2 is cleared and RECORDS is displayed in *DS4 
mode. 
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Note: When changing display modes, the displayed subfile data is removed from 
the display. However, the subfile data is not cleared from the subfile table. 


The following keywords are ignored if the display modes have changed: 


Table 3-5. Keywords Ignored If Display Modes Are Changed 


Keywords Additional Information 

ALWROL When a record is not on the screen, it cannot be rolled. 

ASSUME The records with the ASSUME keyword remain on the screen 
when the file is opened. When the display modes change, the 
records on the screen are cleared. This is similar to specifying 
the ASSUME keyword without the OVERLAY keyword. The 
display size of the file with the KEEP keyword must equal the 
display size of the file with the ASSUME keyword. 

CLRL All lines will be cleared by a change in display mode. 

ERASEINP/INZINP When the display modes change, the record is displayed with 

ERRMSG PUTOVR not in effect, even if the record was on the screen 

ERRMSGID before the display modes changed. 

KEEP 

OVERLAY 

PROTECT 

PUTOVR 

PUTRETAIN - 

SFLMSG 

SFLMSGID 


Positioning the Cursor after an Output Operation 
You can specify where you want the cursor positioned after an output operation by 
using the CSRLOC or DSPATR(PC) keyword. 


On the record-level keyword CSRLOC, you can specify the names of two 3-byte 
zoned decimal hidden fields that contain the exact line and position for the cursor 
location. With the CSRLOC keyword, you can position the cursor outside the 
record you are displaying. 


The field-level keyword DSPATR(PC) positions the cursor at the first position of the 
field after the record is written. However, if the OVERLAY keyword is specified at 
the record level, the cursor position may be lost after subsequent write operations. 


Note: The cursor is not positioned if the keyboard is unlocked before the output 
operation. 


If both the CSRLOC and DSPATR(PC) keywords are specified, the cursor is posi- 
tioned by the CSRLOC keyword. If several fields have DSPATR(PC) keyword 
specified, the cursor is positioned at the first field for which the DSPATR(PC) 
keyword is specified. 


If the CSRLOC and DSPATR(PC) keywords are not specified, the cursor is posi- 
tioned at the first input-capable field on the display. If there is no input-capable 
field, the cursor is positioned in the upper-left corner of the display. However, if the 
CSRLOC and DSPATR(PC) keywords are not specified for records containing 
input-capable fields, the cursor position may be lost if the record is suspended and 
then restored. For example, the cursor position may be lost if the F1 (Help) key is 
pressed after the record is displayed. 
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Other DDS functions can affect the write operation. For a write operation to a user- 
defined data stream (USRDFN keyword), the functions performed are determined 
by the user-supplied controls. 


Returning the Cursor Position to an Application 
You can determine where the cursor was positioned on input by using the 
RTNCSRLOC (return cursor location) keyword. 


This keyword may be specified in either of two formats: 


e Return the name of the record and field in which the cursor is currently posi- 
tioned. Optionally, a third parameter may be specified that will contain the rela- 
tive cursor position within the field. 


e Return the row and column position of the cursor relative to the display. 
Optionally, two additional parameters return either of the following: 


— The row and column position of the cursor relative to the active window (if 
one exists) 

— The location of the cursor at the beginning of a two event mouse button 
call. 


The parameters of these formats are described in the DDS Reference. 


Returning the Cursor Position Within a Subfile to an Application 
On input, you can determine where the cursor is located in a subfile by using the 
SFLCSRRRN (subfile cursor relative record number) keyword. The relative record 
number on which the cursor is positioned is returned in the hidden field specified as 
the parameter on the keyword. The field must be defined in the record format as a 
signed numeric (S in position 35) with a length of 5 with zero decimal places. Also, 
it must be a hidden field (H in position 38). 


Returning the Mode of a Subfile to an Application 

You can use the SFLMODE (subfile mode) keyword to determine whether the 
subfile was in folded or truncated mode on input. The mode parameter is required. 
The SFLMODE keyword is only valid for subfile control records and the SFLCTL 
keyword must be specified. 


The field specified for the mode parameter is defined in the record format as a 1 
character (A in position 35) hidden field (H in position 38). The field is returned 
with a value of 0 if the subfile is folded and with a value of 1 if the subfile is trun- 
cated. If SFLDROP (subfile drop) or SFLFOLD (subfile fold) is not specified on the 
SFLCTL (subfile control) record, the value is always returned as 0. 


Initializing Output/Input Fields 

Device support saves all data read from input-capable fields for records currently 
on the display in a save area. The output/input fields within this save area are 
updated on output operations. 


For output operations, the following happens: 


e Input-only fields are initialized to zeros (numeric fields), blanks (character 
fields), or a default value (DFT keyword) from the display file. 

¢ Output/input fields, hidden fields, and program-to-system fields are initialized to 
the contents of the output buffer. If this output operation is caused by the ini- 
tialize record function (INZRCD keyword), no output buffer is available. 
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Output/input fields and hidden fields are initialized similar to input-only fields. 
Output/input fields are input and output capable. 
¢ Output-only fields are not part of the input buffer unless they are part of a 
subfile record, in which case they are saved as if they were output/input fields. 
e All response indicators for this record are set off. 


Note: For input-capable fields, if the PUTRETAIN or ERASEINP keyword is in 
effect, the save area for the field remains unchanged. 


Neither the input nor the output buffer is changed during write operations. 


Inviting Input to the Display 
The invite operation is used to send a request for input to a display station and 
return to the program without waiting for the input to arrive. This allows a program 
to request input from one or more display stations but continue processing without 
waiting for any of the display stations to respond. When the program is ready to 
process the input, the data can be received from any of the invited display stations 
by performing a read-from-invited-devices operation. 


The invite operation is done by performing a write operation using a record format 
with the INVITE DDS keyword in effect. Refer to the appropriate high-level lan- 
guage manual to determine how to perform a write operation and how to use indi- 
cators to control the INVITE DDS keyword. 


Once a display station is invited, the valid operations to receive data from the 
display station are the read-from-invited-devices operation and the read(wait) oper- 
ation directed to a specific display station. Cancel invite is also a valid operation to 
an invited display station. 


Before a display station can be used for I/O operations in a multiple-device display 
file, it must be acquired to the file. A program can direct the invite operation to any 
display station currently acquired for the file. 


If the multiple-device display file was created with DFRWRT(*YES) specified, an 
output operation with the INVITE DDS keyword optioned on will cause the output 
that has been postponed to be displayed on the screen before the display station is 
invited. 


If you want to invite a display station but have no data to send to it, perform the 
output operation with a record format which contains the INVITE DDS keyword 
optioned on but has no output-capable fields. 


Multiple-display station display files are supported in ILE RPG*, ILE COBOL*, ILE 
C*, and CL. 


Inviting Input from CL Programs: The invite operation is available directly to CL 
programs through CL commands: 
¢ WAIT(*NO) on RCVF and SNDRCVF Commands: 


WAIT(*NO) allows overlapping of I/O operations and the running program, 
requests for input from more than one display, and receiving input as it is avail- 
able. This provides support equivalent to the invite operation. 


On a read operation with the no-wait option, the system sends the request to 
the display and returns to the program. However, the requested record is not 
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available when control returns. The purpose of this operation is to make the 
display station eligible to send input data while the program performs other 
work. 


To retrieve the record, issue a WAIT command. The WAIT command issues a 
read-from-invited-devices operation. The program waits until data is available 
from the display station or the WAITRCD time elapses. Then, the display 
station name and any input data are passed to the user program. If more than 
one read-with-no-wait operation has been issued (each to a different display) 
and more than one completes, the WAIT command processes only the first 
read-with-no-wait operation that is completed. 


A WAIT command can be issued to process each of the other read-with-no-wait 
operations. They are processed in the order of completion. 


When a record containing the INVITE keyword is sent to the display, the opera- 
tion is handled as a write-read operation with a no-wait option. The INVITE 
DDS keyword is ignored on the write-read operation. 


A write-read operation with a no-wait option is the same as a write followed by 
a read-with-no-wait. 


e ENDRCV Command: 


The ENDRCV command is used to end a request for input made with the 
WAIT(*NO) option. The ENDRCV command ends the input request even if 
data is available from the display station. If data is being sent by the display 
station when the ENDRCV operation is performed, the data is lost. If the 
display station is not invited, the application program is signaled with an error. 


Reading Invited Input from the Display 
The read-from-invited-devices operation provides a means of waiting for and 
receiving data from any one of the invited display stations. This method of inviting 
a display station and then reading from the invited display station is useful when 
the application must control the amount of time spent waiting for the user to 
respond. When the read-from-invited-devices operation is performed, the program 
waits for the time interval specified on the WAITRCD keyword of the CRTDSPF, 
CHGDSPF, or the OVRDSPF command. The wait can be ended in the following 
ways: 


e Data becomes available from an invited display station. The display station 
name, the results of the operation, and any input data are passed to the 
program. When data has been received, the display station is no longer invited 
and must be invited again by an invite operation if more data is to be received 
from the display station by a read-from-invited-devices operation. 


e No-display station-invited signal. |Indicates that none of the display stations 
associated with the file are in the invited condition. Refer to the appropriate 
high-level language manual for information on how this will be communicated to 
the program. 


e Job-ended-controlled signal. \ndicates that the job that the program is running 
in is being ended with the controlled option through the End Job (ENDJOB), 
End System (ENDSYS), Power Down System (PWRDWNSYS), or End Sub- 
system (ENDSBS) command. Refer to the appropriate high-level language 
manual for information on how this will be communicated to the program. This 
occurs only once in a process no matter how many multiple-device display files 
are in use. All invited display stations remain invited. 
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¢ No-invited-devices-have-data-available signal. This occurs when no display 
stations associated with the file have data available, the WAITRCD time is 
*IMMED, and none of the previous conditions apply. The invited display 
stations remain invited. Refer to the appropriate high-level language manual 
for information on how this will be communicated to the program. 


e Time-out-on-wait-for-data-from-invited-devices signal. This occurs when the 
WAITRCD value is a finite number of seconds, no data became available 
during that interval, and none of the previous conditions apply. Refer to the 
appropriate high-level language manual for information on how this will be com- 
municated to the program. The invited display stations remain invited. 


Also, ILE COBOL provides a means of performing the read-from-invited-devices 
operation as if WAITRCD(*IMMED) had been specified. See the ILE COBOL 
books for information on the NODATA phrase and its effect on the read-from- 
invited-devices operation. 


Understanding the Read-From-Invited-Devices 

When the program is ready to process input from one of the invited display 
stations, it can issue a read-from-invited-devices operation. This operation waits for 
a specified time for input to arrive from one of the invited display stations. The time 
limit can be specified when the display file is created and can subsequently be 
changed or overridden. If no invited display stations respond within the time limit, 
the program receives an indication that the time limit expired and can continue pro- 
cessing. If an invited display station responds within the time limit, the program can 
determine which display station responded and the record format used to process 
the data. The other invited display stations remain invited and can be sending 
data. The responding display station can also be invited again by another invite 
operation. 


A read operation can also be directed to a specific display station. This operation 
will not complete until the specified display station responds with data. The display 
station need not be invited for the read operation, but, if it is, the program will wait 
for input and the display station is no longer invited. 


e The read-from-invited-devices operation only accepts data from display stations 
which are currently invited. 


e If more than one display station acquired to the display file has an invite out- 
standing, a read-from-invited-devices operation will return the next available 
record from one of the invited display stations. If records are received from 
more than one display station before the read-from-invited-devices operation, 
the other records will be kept for a subsequent read-from-invited-devices opera- 
tion or for a subsequent read(wait) operation directed to a specific display 
station. 


e When a display station has responded and the input is received by the read- 
from-invited-devices operation, that display station is no longer invited. It can 
be invited again by another invite operation but this should not be done until all 
the record formats on the display with input-capable fields have been read. 


¢ A record format cannot be specified on the read-from-invited-devices operation. 
The record format returned from a display is the same as the last record format 
written to the display station. 


e The timing function associated with the WAITRCD parameter may not force an 
end to the wait if the system is processing the Help key. In the following 
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cases, the read-from-invited-devices function will not end until the user exits 
from the help information: 


— The system is displaying help that is defined by H specifications in the DDS 
for the display file. 


— The system is displaying help for a message when the display station is the 
requester display station for the job and the display file specifies 
MAXDEV(1). 


You can force message help to end when the WAITRCD time ends by speci- 
fying a value greater than 1 for the MAXDEV parameter on the CRTDSPF or 
CHGDSPF command. 


Reading-From-Invited-Devices from CL Programs: The read-from-invited- 
devices operation is available directly to CL programs through CL commands. To 
retrieve the record, issue a WAIT command. The WAIT command issues a read- 
from-invited-devices operation. The program waits until data is available from the 
display station or the WAITRCD time elapses. Then, the display station name and 
any input data are passed to the user program. If more than one read-with-no-wait 
operation has been issued (each to a different display) and more than one com- 
pletes, the WAIT command processes only the first read-with-no-wait operation that 
is completed. 


A WAIT command can be issued to process each of the other read-with-no-wait 
operations. They are processed in the order of completion. 


When a record containing the INVITE keyword is sent to the display, the operation 
is handled as a write-read operation with a no-wait option. The INVITE DDS 
keyword is ignored on the write-read operation. 


A write-read operation with a no-wait option is the same as a write followed by a 
read-with-no-wait. 


Reading Input from the Display 
A read operation passes a record from the system to the program. The display 
file record format contains the information necessary for the system to handle the 
record. The user must perform a required action such as pressing the Enter key or 
a function key to pass the data to the system. The read operation results in the 
following: 
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Read Operation 


a _ 


(i | _——<—$—a 


Program 


C™\ 
[ ! Returns data 
! KO to program 
Unlocks 
keyboard Locks keyboard 
(If locked) after user action Sade 


For input operations, the following happens in the order given: 


1. For an input-only operation, all response indicators for this record are set off 
and the read operation is issued. 


2. Character fields received from the display are right- or left-justified and padded 
with blanks or truncated as necessary. The default is left-justify, which can be 
overridden using the AUTO or CHECK keyword. 


3. Numeric fields received from the display have the following done to them: 


a. If the field is negative, the zone portion of the units position is set to a D 
(see “Handling Negative Numeric Input Data” on page 3-40). 

b. All nonnumeric characters are removed and the numeric characters are 
compressed. 

c. Signed numeric fields are right-justified and numeric-only fields are decimal 
aligned. 

d. The field is padded with zeros or truncated as necessary. 

e. Field validation is performed. 


All fields received from the display whether they are part of the selected record or 
not are handled in this way. 


If any field validation errors are detected, a message is sent to the user so that the 
error can be corrected. This process is repeated until there are no longer any 
errors. The save area for the requested record is then copied into the input buffer. 


Note: To process input data for a read operation with no record format name, 
display station support uses the last record written to the display that con- 
tains at least one of the following: 


e Input-only fields 
¢ Output/input fields 
e Hidden fields 


If no such format is on the display, display station support uses the last 
format written to the display that did not contain these kinds of fields, for 
example, an output-only record that specifies valid command keys. If no 
such record exists on the display, an error message is returned to the 
program. 
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A record does not have to be written to the display before it can be read by the 
program with the INZRCD keyword. The system does this the same way an appli- 
cation program performs an output operation with the exception of the following: 


e For an output-only field, no user data is available so the field is initialized to 
blanks. If the field is edited, the editing is ignored. If the BLKFOLD keyword is 
specified, it is ignored. 

e For an output/input field, no user data is available so the field is initialized to 
blanks. If the field is edited, the editing is ignored. The field actually contains 
null characters (hexadecimal zeros), which appear as blanks. 

e For a constant or input-only field, the data does not normally come from the 
output buffer so the field appears the same as when the program displays it 
using a write operation. 

e For a hidden field, the field is returned on a read operation as blanks (hex 40) if 
the field is a character field or zeros (hex FO) if the field is a numeric field. 

e For a message, there is no message data so the field is ignored. 

¢ The LOGOUT keyword is ignored. 

¢ The ERRMSG and ERRMSGID keywords are ignored because the record is 
not already on the display. 

¢ The SFLMSG and SFLMSGID keywords are ignored. 


All other fields or keywords are processed as if they were selected on an output 
operation. 


Unlocking the Keyboard while the Program Is Processing Data 
The keyboard can be unlocked so that data can be entered into input fields while 
the program is processing previously entered input data with the UNLOCK keyword. 


Normally, input fields are not erased until after the keyboard is unlocked. Ona 
read operation, input fields are erased after the keyboard is unlocked only if the 
UNLOCK keyword is specified and the GETRETAIN keyword is not specified. 


For the 5250 display station, the read operation with the UNLOCK keyword in effect 
results in the following: 


1. The 5250 display station does a hardware validity check on the fields. If no 
errors are found, the following is done: 


a. If the UNLOCK keyword is specified without the GETRETAIN keyword or if 
the UNLOCK(*ERASE) keyword is specified, all input-capable fields that 
are changed are cleared. 

b. If the UNLOCK keyword is specified with the GETRETAIN keyword or if the 
UNLOCK(*MDTOFF) keyword is specified, all modified data tags (MDTs) 
are reset. 

c. If the UNLOCK(*“ERASE *MDTOFF) keyword is specified, all input-capable 
fields that are changed are cleared and their MDTs are reset. 

d. The cursor is repositioned to the field where the user can enter the next 
record. 

e. The keyboard is unlocked. 


2. The system validity checks all the fields for all records on the display. If errors 
are detected, normal error retry is performed. A user could be typing into the 
next record when an error message is displayed. 


Note: The error message could refer to data that is no longer on the display 
because the data was erased. 
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3. Control returns to the program. 


Notes: 


1. If an application program detects input errors and sends error messages to the 
display, the messages may refer to input that has been typed over. 


2. If the CHANGE keyword is specified and either the UNLOCK keyword is speci- 
fied without the GETRETAIN keyword or with the UNLOCK(*ERASE) keyword 
is specified, the associated response indicator is set on for the next input 
record. 


3. When a read operation with the UNLOCK keyword (and without the 
GETRETAIN keyword) or the UNLOCK(*ERASE) keyword is used for a record 
while a subfile is on the screen, subfile records may be returned to the program 
on a subsequent get-next-changed operation to the subfile even though the 
user did not enter data into the subfile record. It is recommended that you use 
the UNLOCK(*ERASE *MDTOFF) keyword instead of the UNLOCK keyword 
(without the GETRETAIN keyword) or the UNLOCK(*ERASE) keyword. If you 
must use either of the latter, you should make sure that your high-level lan- 
guage program compares for blanks to handle the possibility that an unmodified 
field containing all blanks is returned to the program. 


Keeping Input Data 

Input data on a display can be kept after the user presses the Enter key with the 
GETRETAIN keyword. The GETRETAIN keyword can only be used with the 
UNLOCK keyword. 


Setting an Indicator When Data Is Changed 
A response indicator can be set on when data is entered into an input field or when 
data is changed in an output/input field with the CHANGE keyword. 


Initializing Records and Unlocking the Keyboard—Diagram 
The following diagram shows the effect of INZRCD and UNLOCK keywords on an 
input operation: 


Before J After 
fs N 
Get A ot Used 
with INZRCD 
D > A 
CG Not Used 
Get E 
with INZRCD Not Used 
and UNLOCK 
| E 
Not Used 
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Note: Record formats A, D, and E occupy the same lines. 
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Record formats B, D, and C are erased if the OVERLAY keyword is not speci- 
fied for record format A. Record format A is displayed with constants and ini- 
tialized input fields. The keyboard is unlocked. The keyboard is locked after 
the user satisfies the get operation. 


1 Record formats B, D, and C are erased if the OVERLAY keyword is not speci- 
fied for record format E. Record format E is displayed with constants and ini- 
tialized input fields. The keyboard is unlocked. After the user satisfies the 
read operation, the contents of the input fields are erased and the keyboard is 
unlocked again. 


Note: Even though the UNLOCK keyword is specified, field validity checking, if 
specified, and command key verification are performed. Therefore, a user 
could be typing into the next record when an error message is sent to the 
display. 


Specifying Validity-Checking Functions 


Two methods can be used to check the validity of data entered by the user: 


e Have the system check the data before it is passed to the application program. 
e Have all the input data passed to the application program, which checks the 
validity of the data. 


In either case, if errors are detected, a message is displayed informing the user of 
the error so that it can be corrected. If you choose the second method for 
detecting errors, see “Creating and Displaying Your Own Messages” on page 8-1 
for information on how your program can display error messages. The rest of this 
section gives more information on the first method, when the system detects the 
errors before passing the data to your program. 


The validity-checking functions you can specify in DDS are: 


¢ Detecting fields in which at least one character must be entered (CHECK(ME) 
keyword). Blanks are valid characters. This is referred to as mandatory enter. 

¢ Detecting fields in which every position must contain a character (CHECK(MF) 
keyword). Blanks are valid characters. This is referred to as mandatory fill. 

e Detecting incorrect data types where character, numeric, or signed numeric 
data is required. 

¢ Detecting data that is not in the range specified for the field (RANGE keyword). 

e¢ Performing comparison checking between data entered and specified constant 
value (COMP keyword). 

¢ Comparing the data entered to a specific list of valid entries (VALUES 
keyword). 

¢ Detecting if a valid field or record name was entered in a character field 
(CHECK(VN) keyword). 

¢ Detecting if a valid object name was entered in a character field (CHECK(VNE) 
keyword). 

¢ Performing modulus 10 or 11 check digit verification (CHECK(M10) or 
CHECK(M11) keyword). (Only one can be specified.) 

e Allowing blank-key entries to be processed as if no entry had been made 
(CHECK(AB) keyword). CHECK(AB)—Allow Blanks—is ignored if the subfile 
keyword SFLROLVAL or SFLRCDNBR is also specified for the field. 

¢ Detecting if a space, a plus sign, or a minus sign is embedded between 
numeric digits in a numeric field. Also, detecting if a plus sign or minus sign 
precede a numeric digit in a numeric field. To detect such cases, use the Vali- 
date Numeric (VALNUM) keyword. 
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The ERRSFL keyword can be used in addition to the validity checking keywords 
CHECK(M10 M11 VN VNE), COMP, RANGE, and VALUES to allow more than one 
of the error messages associated with the keywords to be displayed at one time. 


When you specify the RANGE, COMP/CMP, VALUES, CHECK(VN), CHECK(VNE), 
CHECK(M10), or CHECK(M11) keyword for validity checking and an error is 
detected by one of these validity checking functions, the following happens: 


1. The keyboard is locked. 

2. All fields in error are displayed in reverse image. If a field in error has both the 
underline (UL) display attribute and the highlight attribute (HI), its image is not 
reversed, as this combination of attributes has the same effect as 
DSPATR(ND). 

3. The cursor is positioned at the beginning of the first field in error. 

4. A system-supplied error message for the first field in error is displayed on the 
error line, 


or, 


If you have chosen to provide your own error message for a field using the 
CHKMSGID keyword and this is the first field in error, then your error message 
is displayed on the error line. 


If your controller is installed with the self-check feature (see the 5250 Functions 
Reference), the controller performs validity checking for the CHECK(M10F) and 
CHECK(M11F) keywords. Errors are detected when you attempt to move the 
cursor from the input field rather than when you press the Enter key or a Command 
Attention key. The Operator Error Code 00115, rather than a system-supplied or 
user-specified message, is displayed in the lower left corner of the display. If the 
USRDSPMGT keyword is also specified, CHECK(M10) and CHECK(M11) function 
as CHECK(M10F) and CHECK(M11F). 


If the RANGE, COMP, VALUES, CHECK(VN), or CHECK(VNE) keyword is speci- 
fied for a field, and data is entered into that field, the field indicates that it has been 
changed regardless of attempts by the user to restore the field after an error. If 
blanks (for character fields) or zeros (for numeric fields) will fail the validity checking 
function, use the CHECK(AB) keyword. This will satisfy the validity checking func- 
tion. 


When you specify validity checking for records that are part of a subfile, each field 
in the record is validity checked before it is placed in the subfile from the display. 
You cannot roll the records until all fields in error are corrected. 


The system only performs validity checking on a field if the field is changed by the 
user or if its modified data tag (MDT) is set on using DSPATR(MDT). 


Notes: 


1. If the user presses the Dup key, any validity checking for a field is ignored. 
The DUP keyword lets the user use the Dup key. 


2. The value for a numeric field for which the COMP, VALUES, or RANGE 
keyword is specified is aligned based on the decimal positions specified for the 
field and filled with zeros where necessary. If decimal positions were not 
entered for the field, the decimal point is assumed to be to the right of the digit 
to the extreme right in the value. For example, for a numeric field with length 
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of 5 and decimal positions of 2, the value 1.2 is interpreted as 001.20 and the 
value 100 is interpreted as 100.00. 


3. When you use the RANGE keyword for validity checking an input field and 
blanks are entered in the input field, the value for the input field may not meet 
the range requirements. Blanks are converted to zeros for numeric fields and 
are passed as blanks for character fields. Use the field level keyword BLANKS 
to determine when a field is displayed as all blanks. The response indicator on 
the BLANKS keyword is set on if the user enters blanks. 


Understanding the Limitations on the Number of Input-Capable 
Fields 

For a remote 5250 display station (a display station attached through a remote con- 
troller), you can specify as many as 126 or 256 input fields on one display, 
depending on the controller model. (The 5294 controller supports 126 input fields; 
the 5394 controller supports 256 input fields.) Additionally, if either DSPATR(OID) 
or DSPATR(SP) is specified, this maximum is reduced by 1 for each three 
instances of these keywords. If fewer than three instances occur, it is still reduced 
by one. 


For a local 5250 display station (a display station attached through the local display 
station controller), you can specify as many as 256 input fields. Also, if either 
DSPATR(OID) or DSPATR(SP) is specified, this maximum is reduced by 1 for each 
three instances of these keywords. In addition, any use of the magnetic stripe 
reader on a local 5250 display station also reduces the maximum number of fields. 
The maximum number of fields is calculated as follows: 


256 - [22 +o | rounded up to the next whole number 
RSLH131-2 


A is the number of DSPATR(OID) and DSPATR(SP) fields on the display and B is 
the length of the longest expected magnetic stripe input where 125 data characters 
is the maximum allowed. Magnetic stripe data not specified as DSPATR(OID) can 
be entered into any input field. 


If the maximum number of input fields is exceeded in any of the preceding cases, 
message CPF5192 is issued to the using program. 


No maximum-number-of-fields diagnostic is provided during display file creation 
because the number of fields and record formats is not known until the program is 
run. 

When a subfile record is displayed, the actual number of input-capable fields sent 
to the display is the number defined in the record multiplied by the number of 
subfile records that are displayed. 


For remotely attached 3270 displays, the limitation is 126 input fields. 


For ASCII displays attached through a protocol converter, the limitations are the 
same as the controller to which they are attached. 
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Handling Negative Numeric Input Data 
The negative sign in numeric input data can appear in three forms: 


¢ Hex 60 if the sign is entered using the - (minus) key 
e Hex D if the sign is entered using the Field Minus key 
¢ Hex Dn if the sign is entered as an alphanumeric character with a D zone 


The hex 60 is treated as a true minus sign if it is to the right of the least significant 
digit. 


The hex D zone is treated as a minus sign if it is the least significant digit. In 
addition, it is treated as a significant digit with a value equal to the numeric portion. 


Imbedded blanks (between significant digits) are changed to zeros before decimal 
alignment. 


Understanding How the System Reads Input from the Display 
When a read operation is issued, the system reads all the records on a display. 
However, only one record is passed to the program for each read operation. The 
system saves all the other records in anticipation of more read operations. 


If each read operation refers to a different record on the display, no action is 
required of the user. However, if each read refers not to a different record on the 
display but to the same record and if the RTNDTA keyword is not specified, the 
user must perform an action such as pressing the Enter key or a CFnn key to start 
the next read operation because each record entered is passed to the program only 
once. If the RTNDTA keyword is specified, the user does not have to perform any 
action because the same input buffer that was returned to the program on the pre- 
vious read operation for the record is returned again. 


The system saves the contents of input-capable fields for records that are active on 
the display. This saved data is passed to the user program and can be altered by: 


¢ Initializing the data with a constant on a write operation. A field can be initial- 
ized with the value specified in a DFT keyword. 

e Entering data through directly typing the data in or using a light pen to select 
data. (The MDT for a field can be set on to simulate user input.) 

e Entering data from a program on a write operation. This applies to output/input 
fields (and output-only fields for subfiles). 

e Initializing the data with blanks (character fields) or zeros (numeric fields) on an 
output operation for the same record unless the PUTRETAIN keyword is speci- 
fied. This applies to input-only fields. 


Writing Output and Reading Input at the Same Time 
The write-read operation is a combination of a write operation and a read operation 
to the same record format in one high-level language statement like the SNDRCVF 
command in a CL program. It behaves as if you had specified a read operation 
immediately following a write operation. 


Some high-level languages have a write-read operation which writes information on 
the display and reads the user response in one statement. For example, ILE RPG 
has the execute format (EXFMT) operation. This kind of operation is useful if you 
need to both present new information on the display and request information from 
the user at the same time. You can also use a write operation followed by a read 
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operation to the same record format to simulate this operation in languages that do 
not support a combined write-read operation. 


When this operation is performed, the following happens: 


1. The program calls the system display support giving it the data to show on the 
display and the record format to use when writing and reading that data. 


2. The system combines that data with the information it finds in the record format 
and constructs the data stream to be sent to the display. 


3. The data stream is then sent to the display and the keyboard is unlocked. 


4. The user types the data in the fields which allow input and presses the Enter 
key or some other function key. 


5. The data is then sent from the display to the system. The system decodes it 
and extracts only the information that the application program needs to know 
and returns that data to the application program. 


When you work with only one record format, this write-read style of working with it 
is the most common. On the write portion of the operation, you provide the data 
that the user will see. On the read portion, you receive data back that the user has 
entered or changed. 


Canceling Input That Was Not Waited For 


The cancel-invite operation is used to cancel the input request issued to a display 
station that was previously invited through the invite operation. The input request is 
canceled by performing a write operation to the invited display station. One of the 
following occurs: 


e If the write request is received before the user responds to the input request 
from the invite operation, the input request is canceled and the record format 
specified on the write operation is sent to the display station. If the record 
format has the option indicator set on for the DDS keyword INVITE, the display 
station is invited again. 


e If the write request is received after the user responds to the input request from 
the invite operation, the input request is not canceled and the write operation 
fails. The read-from-invited-devices operation or a read(wait) operation must be 
issued to receive the available data. 


Releasing a display station also implicitly cancels any input requests directed to the 
display station. If the display station has data available, the data is lost. 


Locking the Keyboard and Positioning the Cursor During I/O 


Operations 


The following lists what happens to the keyboard when a write, write-read, or read 
operation is run: 


Operation Keyboard 

Write The keyboard is unlocked by default. If the LOCK keyword is 
specified, the keyboard is not unlocked. 

Write-Read The keyboard is unlocked. 
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Operation Keyboard 


Read The keyboard is unlocked (if locked) before display station user 
action. After user action, the keyboard is locked by default. If the 
UNLOCK keyword is specified, the keyboard is left unlocked. 


Every time the keyboard is unlocked, the cursor is repositioned. In some cases, 
many write operations between read operations can cause erratic cursor move- 
ment. If the user starts typing before the last write operation, the cursor is reposi- 
tioned when the keyboard is unlocked and this can cause confusion for the user. 
You can prevent this by using the LOCK keyword. By using the LOCK keyword on 
each write operation but the last, the keyboard remains locked until the last write 
operation. This avoids erratic cursor movement, but prevents the user from starting 
to type data. 


Normally, a user action, such as pressing a valid command key, locks the key- 
board. 


To specify that the system unlock of the keyboard on the next input operation 
should not occur, specify the retain lock status (RETLCKSTS) keyword. This 
keyword prevents the loss of data when the input operation is started and data is 
already being transmitted from the keyboard. 


Note: Use the RETLCKSTS keyword only when the keyboard is already unlocked. 


To position the cursor with the DSPATR(PC), CSRLOC, or 
SFLRCDNBR(CURSOR) keyword, the keyboard must be locked. Only the fol- 
lowing conditions on an output operation cause the keyboard to be locked and must 
be present for the display station to position the cursor. (An output operation 
normally unlocks the keyboard before it ends unless the LOCK keyword is specified 
so these conditions lock the keyboard only momentarily.) 


e Input-capable fields are erased (ERASEINP keyword). 

¢ Modified data tags are reset (MDTOFF keyword). 

e Any input-capable field is written to the display. 

¢ The complete display is erased (a write operation without an OVERLAY 

keyword). 

e The 5250 format buffer is reset, which can be the result of: 
— A record format with an input-capable field is overlaid or erased. 
— A record format with a cursor location specification is overlaid or erased. 
— The PROTECT keyword is specified on the record being written. 


For the cursor positioning keyword to take effect, the keyboard must go from the 
lock condition to an unlocked condition. That is, if the keyboard is unlocked prior to 
the write operation, the cursor positioning keyword does not take effect immediately 
on the write operation. However, there is one exception. If the keyboard is tempo- 
rarily locked during an output operation, the cursor positioning keyword will be in 
effect if the output operation unlocked the keyboard at the end. 


In addition, if any of the preceding conditions happens on a write operation, the 
keyboard must be unlocked before any user action either by the same operation or 
by a following operation (it should be the last write operation). 


A write operation to a subfile never unlocks the keyboard because no input or 
output is sent to the display station. 
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Saving Previously Displayed Information 


A display file may be opened to a display station even when another display file is 
already using that display station. When an I/O operation is performed to the 
second display file, the first display file is suspended. 


When a display file is suspended, the information on the display can be saved 
automatically by the system if you specify *YES for the RSTDSP parameter on the 
Create Display File (CRTDSPF) or Change Display File (CHGDSPF) command. 
The contents of a display file can then be restored when an I/O operation is later 
performed to that display file. If *NO is specified for the RSTDSP parameter, the 
application program needs to rewrite the display to show it again. 


The RSTDSP parameter lets you overlap a program call, keyboard input, and file 
I/O processing, as shown in the following example: 


Display File 
ee 1 DSPFILY 
Write......... 

Write......... 
3 —« 
Read.......... | | — >| RCD Y1 
Display File 
DSPFILX 


————+| _RCD X1 
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Program 1 issues a write operation to record format RCD Y1 in display file 
DSPFILY, which activates display file DSPFILY. 


1 Program 1 issues a write operation to record format RCD X1 in display file 
DSPFILX, which suspends display file DSPFILY and activates display file 
DSPFILX. If RSTDSP(*YES) is specified for display file DSPFILY, the data 
displayed on the display station is saved. If RSTDSP(*NO) is specified 
instead, the data is lost and the program needs to write the information in RCD 
Y1 again to show it. 


Program 1 issues a read operation to record format RCD Y1, which suspends 
display file DSPFILX and restores display file DSPFILY. If the RSTDSP(*YES) 
parameter is specified for DSPFILY, then the data displayed on the display 
station when DSPFILY is suspended can be restored. 


When RSTDSP(*YES) is specified for a display file, and you are suspending and 
restoring that display file because of operations to another display file, some dis- 
plays may appear to flash on the screen briefly. If a display file has a record on 
the display and an I/O operation is done to a second display file, the first file is 
suspended and its screen contents are saved. When returning to the first display 
file, the display file and its screen contents are restored. If a write operation is 
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done to a different record format in the display file, the restored display will flash 
briefly before the output operation is complete. If you are going to completely 
rewrite the display contents from your program when going back to the first file, use 
RSTDSP(*NO). 


You should specify *YES for the RSTDSP parameter in the following situations: 
e When you are writing a record that has the following keywords in effect: 


— CLRL 

— OVERLAY 
— PUTOVR 

— PUTRETAIN 
— ERRMSG 
— ERRMSGID 


You must ensure that the records that are on the display are the records that 
these keywords apply to. If the display file is suspended, the data must be 
restored to the screen so that the write operations to the record formats that 
use these keywords are valid. 


e¢ When you perform multiple read operations to a record format on the display 
without intervening write operations. If you should call a program while pro- 
cessing the data that has been read and that program presents a display of its 
own, the subsequent read operation done by your program restores the display 
properly. 


Saving and displaying data again requires significant system and data transmission 
overhead. For a 1920-character 5250 display station, approximately 3000 charac- 
ters are transmitted each time the display data is saved displayed again. To avoid 
this overhead, write your application programs to do the following: 


¢ Make the programs in the application share the same copy of the display file 
among themselves by specifying SHARE(*YES) on the display file. 


e Perform complete display rewrites each time the programs in the application 
write to the display. A complete display rewrite occurs when a record is written 
to the screen and the OVERLAY keyword is not used or implied. 


Note: If complete display rewrites are not performed and if new input fields, 
occupying positions on the screen above the currently displayed fields, 
are sent to the display, the program receives a message (CPF5192). 
This occurs because the 5250 display station requires that new input 
fields sent to the display appear in lower positions than input fields cur- 
rently on the display. In normal operations, data management performs 
field processing to satisfy the 5250 requirement. See “Avoiding Record 
Format Problems on the 5250 Display Station” on page 3-45. 


When one program that uses a display file with the SHARE(*YES) parameter speci- 
fied calls another program that uses the same display file, the display file is not 
suspended even though both programs have opened the file. If the display file is 
not shared, the system maintains separate copies of the display file for each 
program and suspends and restores the display files separately. 


Since system programs do not specify file sharing, you should specify 
RSTDSP(*YES) on the CRTDSPF or CHGDSPF command if your program con- 
tains a display file and calls system functions that present displays. System func- 
tions that break into the normal path of an application, however, such as the 
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System Request Menu or the presentation of break messages, restore the display 
without RSTDSP(*YES) specified. 


To display saved display data again after a close operation is issued to a sus- 
pended file, specify the KEEP keyword for a record format in the saved display 
data. 


Understanding the Effects of I/O Operations on Command Keys 
Read and write operations may or may not affect how the function keys work: 


e Awrite or write-read operation for which no input or output is sent to the 
display does not affect which keys are valid. Examples of such operations are 
a write operation or an update operation to a subfile record format. 


e If awrite or write-read operation displays a message by selecting either the 
ERRMSG or ERRMSGID keyword, the command keys in effect on that output 
operation are valid. Therefore, you can specify a different set of command 
keys to be valid if an error occurs. 


e If only one subfile record format is displayed and the subfile control record 
format specifies a CAnn or CFnn key for the SFLDROP keyword, that key 
remains valid for that function as long as the subfile is still on the display. In 
addition, the key specified for the SFLENTER keyword remains valid until 
another write or write-read operation is done. At the next output operation, the 
specifications for that record apply. 


e lf two subfile record formats are displayed and both specify the SFLDROP 
keyword, only the last SFLDROP keyword is used. There can only be one 
drop key at a time. 


Avoiding Record Format Problems on the 5250 Display Station 


Because of the characteristics of the 5250 display stations, certain record format 
positioning and operational combinations can produce undesirable results. The fol- 
lowing example illustrates a combination that can cause undesirable results and 
explains how to avoid these results. 


The displays produced and the DDS for the record formats follow: 
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Enter all information regarding the subscriber: 


Last name: First name: MI: 
Street: Apt: 
City: State: AP: e 


DETAIL 
record 
format 
CA1-Display state table, CA2-Display subscription table 
RSLH166-0 
c > 
Alabama_ AL Alaska AS Arkansas AK Arizona AK 
Califomia CA Delaware DEDSTColumbia DC Florida DC STATES 
Y-More state names, N-No more state names record 
Enter all information regarding the subscriber: ) format 
Lastname: Doe First name: John MLE 
Street: _112 Elm Apt: 3A 
City: Anytown _ State: AP: - 
DETAIL 
record 
format 
CA1-Display state table, CA2-Display subscription table 


RV2W047-0 
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A R RCDA 

A FLD1 1 I 2 4DSPATR(PC) 

A* STATES record format follows 

A R STATES OVERLAY 

A SNAME1 12 O12 

A SCODE1 2 0115 

A SNAME2 12 O 118 

A SCODE2 2 0 131 

A SNAME3 12 O 1 34 

A SCODE3 2 0 147 

A SNAME4 12 O 1 50 

A SCODE4 2 0 1 63 

A 

A 

A : 

A SNAME8 12 O 2 50 

A SCODE8 2 O 2 63 

A 3  2'Y-More state names, N-No more + 
A state names' 

A MORESNAM 1 I 3 48VALUES('Y' 'N') 

A* DETAIL record format follows 

A R DETAIL OVERLAY CAQ1(11) CAQ2(12) 
A 4 2'Enter all information regarding + 
A the subscriber: ' 

A 5 1'Last name:' DSPATR(HI) 
A NAMEL 20 I 512 

A 5 33'First name:' DSPATR(HI) 
A NAMEF 13. I 5 45 

A 5 59'MI:' DSPATR(HI) 

A MI 1 I 5 63 

A 6 1'Street:' DSPATR(HI) 

A 

A STREET 45 I 6 9 

A 6 55'Apt:' DSPATR(HI) 

A APT 4 1 6 60 

A 7 1'City:' DSPATR(HI) 

A CITY 15 I 7 7 

A 7 23'State:' DSPATR(HI) 

A SCODE 2 I 7 30 

A 7 33'Zip:' DSPATR(HI) 

A ZIP1 5 I 7 38 

A 7 44'-' 

A ZIP2 4 1 7 46 

A 

A 

A ‘ 

A 10 1'CA1-Display state table, + 
A CA2-Display subscription table' 


Figure 3-12. Sample DDS to Show Record Format Problems 


Assume that the DETAIL record format is on the screen, and the user is entering 
data for a subscriber. Because the user does not know the state code for the state 
to be entered, he or she presses the CA01 key. 
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Because CA01 is defined as a CAnn key, no data is transmitted to the system 
when the CA0O1 key is pressed. The data, however, remains on the screen. The 
program detects that the CAnn key was pressed because response indicator 11 is 
set on. The program then displays the STATES record format. 


Because the STATES record format is physically above the DETAIL record format, 
the system must resend the field formats for the input fields in the DETAIL record 
format. (The system would also resend the field formats if the STATES record 
format contained only output-only fields and was replacing the RCDA record format. 
In this case, the field formats are resent because a record format (RCDA) with a 
specific cursor location is being removed.) 


The following problems occur because the system resends the field formats for the 
DETAIL record format: 


¢ All the input fields in the DETAIL record format lose their modified data tags 
(MDTs). When the program does the next read to the DETAIL record format 
(for example, when the user presses the Enter key), none of the fields typed in 
before the user pressed the CA01 key are returned to the program. The 
program cannot retrieve that typed data even though the data still remains on 
the screen. 


To avoid this problem: 


— Avoid using a CAnn key. 

— If you must use a CAnn key, avoid writing the format containing the CAnn 
key to the screen and then writing another format that is physically placed 
above the first format if both formats contain input-capable fields. 

— Avoid writing a format to the screen that causes the removal of a format 
containing a cursor location specification. 


¢ The highlight attribute for the constant fields (except Last name) is lost. The 
system does not resend the field format for output-only fields. However, if an 
output-only field immediately follows an input-capable field so that the leading 
attribute character for the output field is in the same position as the ending attri- 
bute character for the input-capable field, the attribute of the output field reverts 
to normal. 


To avoid this problem: 


— Do not specify an output-only field with special display attributes imme- 
diately following an input-capable field. 

— If you must specify an output-only field with special display attributes imme- 
diately following an input-capable field, avoid writing that format to the 
screen and then writing another format that is physically placed above the 
first format if both formats contain input-capable fields. 

— Avoid writing a format to the screen that causes the removal of a format 
containing a cursor location specification. 


Note: The system needs to resend the attributes for the input-capable fields when 
a subfile is rolled from a full page to a partial page, a partial page to a full 
page, or a partial page to a partial page. The two problems mentioned 
above may also occur when resending the field attributes. 
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Releasing an Acquired Display Station from I/O Operations 


The release operation makes a display station ineligible for any further I/O oper- 
ations through a file. This operation is used in multiple display file applications or if 
you are performing error recovery in your program. If the display station being 
released is invited, the invite is ended. If the invited display station had data avail- 
able, the data is lost. The release operation can only be performed on display 
stations that are currently acquired to the file. 


The release operation can also be used to recover from errors from acquire, I/O, 
and release operations. After a display station is released, it must be acquired 
again with another acquire operation before any I/O operations can be directed to 
it. If a program is written to recover from errors by releasing a display station and 
then acquiring it again, a value other than *IMMED should be specified on the 
WAITFILE keyword. This is because it takes the system a short time to transfer the 
allocation of a display station description from a job, to the subsystem, and back 
again. 


Closing Display Files 


The close operation makes the display file ineligible for any further I/O operations 
between the program and the system. Refer to the appropriate high-level language 
manual for information on how to start the close operation. 


If the display file is not being shared, the close operation also implicitly releases all 
the display stations acquired to the file and deallocates any file resources allocated 
by the open operation or the acquire operation. 


If the close operation is successful, the only valid operation to the file is open. If 
the close operation fails, the program should issue the close operation a second 
time. 


Mapping Display Operations to High-Level Language Operations 


The following shows the I/O requests supported by the operating system and the 
equivalent high-level language operations: 


Table 3-6 (Page 1 of 2). Display File Operations Supported by the Operating System and the Equivalent High- 
Level Language Commands 


BASIC ILE C CL ILE COBOL ILE RPG 
Operation Statements Functions Commands Statements Operations 
Open OPEN fopen, _Ropen OPEN OPEN 
Acquire _Racquire ACQUIRE ACQ 
Release _Rrelease DROP REL 
Get Attributes _Rdevatr ACCEPT POST 
Write WRITE fwrite, SNDF WRITE WRITE, 
_Rformat, _Rpgmdev, output 
_Rwrite specifications 
Read(wait) READ fread, RCVF WAIT(*YES) READ Primary or 
_Rformat, _Rpgmdev, secondary 
_Rreadn file input, 
READ 
Read READ RCVF WAIT(*NO) READ 
Cancel Read ENDRCV 
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Table 3-6 (Page 2 of 2). Display File Operations Supported by the Operating System and the Equivalent High- 
Level Language Commands 


BASIC ILEC CL ILE COBOL ILE RPG 
Operation Statements Functions Commands Statements Operations 
Wait WAIT 
Invite fwrite1, SNDF1 WRITE! WRITE! 
_Rformat, _Rpgmdev, 
_Rwritel 
Read from Invited _Rreadindv READ READ 
Device 
Cancel Invite fwrite, SNDF WRITE WRITE 
_Rformat, _Rpgmdev, 
_Rwrite 
Write-Read(wait) _Rwriterd, _Rformat, SNDRCVF WAIT(*YES) EXFMT 
_Rpgmdev 
Write-Read(no-wait) SNDRCVF WAIT(*NO) 
Close CLOSE, END _ fclose, _Rclose RETURN, RCLRSC CLOSE, CLOSE, 
CANCEL, RETRN 
STOP RUN 


1 This is the write operation of a record format with the INVITE DDS keyword selected. 


If an error occurs during an I/O operation to a display file, the major/minor return 
code field in the file dependent I/O feedback area may be used to help diagnose 
the error and determine the error recovery action needed. 


Sharing Display Files in the Same Job 


By specifying the SHARE parameter on the CRTDSPF, CHGDSPF, and OVRDSPF 
commands, you can specify that more than one program share the same path to 
the data or the display station. Using the SHARE parameter allows more than one 
program to share the file status, positions, and storage area, and can improve per- 
formance by reducing the amount of main storage the job needs and by reducing 
the time it takes to open and close the file. 


Using the SHARE(*YES) parameter lets an open data path (ODP) be shared 
between two or more programs running in the same job. An open data path is the 
path through which all input/output operations for the file are performed. It con- 
nects the program to a file. If not specified otherwise, every time a file is opened a 
new open data path is built. You can specify that if a file is opened more than 
once and an open data path is still active for it in the same job, the active ODP for 
the file can be used with the current open of the file, and a new open data path 
does not have to be created. This reduces the amount of time required to open the 
file after the first open, and the amount of main storage required by the job. 
SHARE(*YES) must be specified for the first open and other opens of the same file 
for the open data path to be shared. Specifying SHARE(*YES) for other files 
depends on the application. 


Note: Most high-level language programs process an open or a close operation 
independent of whether or not the file is being shared. You do not specify 
that the file is being shared in the high-level language program. You indi- 
cate that the file is being shared in the same job through the SHARE 
parameter. The SHARE parameter is specified only on the create, change, 
and override file commands. Refer to your appropriate language manual for 
more information. 
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Understanding the Open Operation for Files Shared in a Job 
The following items should be considered when opening a file that is shared in the 
same job by specifying SHARE(*YES). 


¢ You must make sure that when the shared file is opened for the first time in a 
job, all the open options that are needed for subsequent opens of the file are 
specified. If the open options specified for subsequent opens of a shared file 
do not match those specified for the first open of a shared file, an error 
message is sent to the program. (You can correct this by making changes to 
your program to remove any incompatible options.) 


For example, PGMA is the first program to open FILE1 in the job and PGMA 
only needs to read the file. However, PGMA calls PGMB which will delete 
records from the same shared file. Because PGMB will delete records from the 
shared file, PGMA will have to open the file as if it, PGMA, is also going to 
delete records. You can accomplish this by using the correct specifications in 
the high-level language. (In order to accomplish this in some high-level lan- 
guages, you may have to use file operation statements that are never run.) For 
more details, see your appropriate language manual. 


e lf you did not specify a library name in the program or the override command 
(*LIBL is used), the system assumes that the library list has not changed since 
the last open of the same shared file with *LIBL specified. If the library list has 
changed, you should specify the library name on the override command to 
ensure that the correct file is opened. 


¢ Overrides and program specifications specified on the first open of the shared 
file are processed. Overrides and program specifications specified on subse- 
quent opens, other than those that change the file name or the value specified 
on the SHARE or LVLCHK parameters on the override command, are ignored. 


Understanding the Input/Output Operation for Files Shared in a Job 


The system uses the same input/output area for all programs sharing the file, so 
the order of the operations is sequential regardless of which program does the 
operation. For example, if Program A is reading records sequentially from a file 
and it reads record 1 just before calling Program B, and Program B also reads the 
file sequentially, Program B reads record 2 with the first read operation. If Program 
B then ends and Program A reads the next record, it receives record 3. If the file 
was not being shared, Program A would read record 1 and record 2, and Program 
B would read record 1. 


For display files, the display station remains in the same state as the last I/O opera- 
tion. 


For display and ICF files, programs other than the first program that opens the file 
may acquire more display or program display stations or release display or program 
display stations already acquired to the open data path. All programs sharing the 
file have access to the newly acquired display stations, and do not have access to 
any released display stations. 
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Understanding the Close Operation for Files Shared in a Job 


The processing done when a program closes a shared file depends on whether 
there are other programs currently sharing the open data path. If there are other 
programs, the main function that is performed is to detach the program requesting 
the close from the file. All other programs sharing the file are still attached to the 
ODP and can perform I/O operations. 


If the program closing the file is the last program sharing the file, then the close 
operation performs all the functions it would if the file had not been opened with the 
share option. This includes releasing any allocated resources for the file and 
destroying the open data path. 


The function provided by this last close operation is the function that is required for 
recovering from certain run-time errors. If your application is written to recover from 
such errors and it uses a shared file, this means that all programs that are attached 
to the file when the error occurs will have to close the file. This may require 
returning to previous programs in the program stack and closing the file in each 
one of those programs. 
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Chapter 4. Displaying Groups of Records Using Subfiles 


A subfile is a group of records that have the same record format and are read from 
and written to a display station in one operation. The following sample display 
shows an example of a subfile: 


CUSTOMER NAME SEARCH 


Search code: 41401 
Prompt 
NUMBER NAME ADDRESS cny STATE Record 
Format 
41401 Adam’s Home Repair 121 GoldenCircle Chicago IL 
41402 Jane’s Radio/TV 135 Ransam Drive = &t Paul MN 
41403 Advanced Electronics 809 8th Street St Paul MN 
41404 Riteway Repair 443 Westem Lane New York NY ; 
41405 Fixtures, Inc. 607 9th Avenue Chicago IL Subfile 
41406 Hall's Electric 200 Main Street St Paul MN 
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Information about DDS keywords 


This chapter uses DDS keywords to describe subfiles. For more information 
about specific DDS keywords, see the DDS Reference. 


Recognizing Subfile Uses 


Subfiles are useful when multiple records that are alike must be displayed. You 
can describe a subfile so that the number of records to be displayed fits on one 
display or exceeds the number of lines available on the display. 


You can use subfiles for the following purposes: 


e Display only, which allows the user to review the subfile records on the display 
(for example, all the line items for a particular order number, or a group of 
records containing customer names and addresses as shown on the previous 
sample display). 


e Display with selection, which allows the user to request more information about 
one of the items on the display. On the first sample display of the following 
example, the user can request the records for a particular customer by entering 
the record number in the record number field. In the second sample display, 
the user can request the records for a particular customer by placing an X in 
the select number field. 
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(— > 
Enter customer number: 41401 
Enter record number: 
RECORD NUMBER NAME ADDRESS CITY STATE 
01 41401 Adam's Home Repair 121 Golden Circle Chicago IL 
02 41402 Jane's Radio/TV 135 Ransom Drive St Paul MN 
03 41403 Advanced Electronics 809 8th Street St Paul MN 
04 41404 Riteway Repair 443 Western Lane New York NY 
05 41405 Fixtures, Inc. 607 9th Avenue Chicago IL 
06 41406 Hall's Electric 200 Main Street St Paul MN 
a = 
Enter customer number: 41401 
SELECT 
RECORD NUMBER NAME ADDRESS CITY STATE 
iS 41401 Adam's Home Repair 121 Golden Circle Chicago IL 
i. 41402 Jane's Radio/TV 135 Ransom Drive St Paul MN 
_ 41403 Advanced Electronics 809 8th Street St Paul MN 
a 41404 Riteway Repair 443 Western Lane New York NY 
£ 41405 Fixtures, Inc. 607 9th Avenue Chicago IL 
= 41406 Hall's Electronic 200 Main Street St Paul MN 


¢ Changing information, which allows the user to change one or more of the 
records in the subfile. The following sample display allows the user to change 
the QTY and SHIP values: 


Order: 


ITEM 

25764 
33624 
49821 
26837 


UPDATE SHIP QUANTITY ON ORDERS 


11589 Customer number: 11111 Customer name: 
DESCRIPTION QTY SHIP 
Pliers 10 10 
Hammer 500 250 
Pliers 200 200 
Wire Cutters 50 25 


Al'Supply 
LOCATION 
RST 

RST 

RST 

RST 


¢ Input only without validity checking, which allows the user to enter data as fast 
as possible; or input only with validity checking, which allows the user to enter 
data that is validity checked by the system or by the program for valid entries. 
The following sample display shows subfiles for input only: 


— 


Enter order number: 


XXXXX 
ITEM NUMBER 

XXXXX 

XXXXX 

XXXXX 

XXXXX 

XXXXX 

XXXXX 

XXXXX 


QUANTITY 
XXX 


¢ Combination of tasks, which can, for example, allow the user to change data as 
well as to enter new records. In the following example, the user can change 
existing names and addresses or enter new records. 


Search code: 


aaa aR: 


CUSTOMER NAME SEARCH 


41401 


NUMBER NAME ADDRESS CITY STATE 
41401 Adam's Home Repair 121 Golden Circle Chicago IL 
41402 Jane's Radio/TV 135 Ransom Drive St Paul MN 
41403 Advanced Electronics 809 8th Street St Paul MN 


¢ Displaying single-choice and multiple-choice selection lists. A single-choice 
selection list is a potentially scrollable list from which the user can select one 
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item. A multiple-choice selection list is a potentially scrollable list from which 
the user can select one or more items. For more information on selection lists, 
see “Selection Lists—Overview” on page 6-24. 


Panel Title 


Single selection list : 


Choice text 
Choice text 
Choice text 
Choice text 
Choice text 
More... 


= 


QANAaaND © 


tiple selection list : 


hoice text 
hoice text 
hoice text 
oice text 
oice text 


More... 


RV3W077-0 


Describing Subfiles in Your DDS Source 


Each subfile you describe in your DDS source requires two types of record formats: 
a subfile record format and a subfile control record format. 


e The subfile record format defines the fields in one row of the subfile. 


The high-level language program uses the subfile record format to read a 
subfile, write new records to a subfile, and update the subfile. Operations to 
the subfile record format are performed between the subfile and the high-level 
language program; the display is not changed on operations to a subfile record 
format. 


The subfile (SFL) keyword is required on the subfile record format. 


e The subfile control record format contains heading information and controls 
subfile functions such as size, initialization, and clearing. 


The high-level language program performs operations on the subfile control 
record format to write the subfile to the display and to read the subfile from the 
display. 


The following DDS keywords are required on a subfile control record format: 


— Subfile control (SFLCTL) keyword, which identifies the subfile control record 
format for the subfile record format that immediately precedes it 

— Subfile size (SFLSIZ) keyword, which specifies the size of the subfile 

— Subfile page (SFLPAG) keyword, which specifies the size of the subfile 
page 

— Subfile display (SFLDSP) keyword, which specifies when to begin dis- 
playing records in a subfile 
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The DDS for the subfile record format must precede the DDS for the subfile control 
record format. 


Each subfile has two types of records: 
e An active subfile record is a record that has been: 


— Added to a subfile by a write operation. 

— Initialized as active by the subfile initialize (SFLINZ) keyword. 

Changed when a write or update operation with the subfile next changed 
(SFLNXTCHG) keyword in effect was issued to the record. 

Changed by the user. 


e An inactive subfile record is a record that was: 


— Not added to a subfile by the write operation. 
— Initialized as inactive by the SFLINZ keyword and the subfile records not 
active (SFLRNA) keyword. 


You can also perform the following functions on subfiles: 


Table 4-1 (Page 1 of 5). Optional Functions for Subfiles 


Function DDS keyword Additional information 

Allow a subfile to contain mes- Subfile message key See the DDS Reference for 

sages from a program (SFLMSGKEY), more information about the 

message queue subfile message subfile message keywords. 
record 


(SFLMSGRCD), and 
subfile program 
message queue 


(SFLPGMQ) 
Clear the subfile of all records Subfile clear The subfile is not erased from 
before new records are written (SFLCLR) the display, however, until the 
SFLDSP keyword is in effect 
on the subfile control record. If 
the SFLCLR keyword is speci- 
fied for a subfile with no 
records, it is ignored. 
Control when to display a Subfile Display The SFLDSP and SFLDSPCTL 
subfile control record Control keywords are the only 
(SFLDSPCTL) or keywords that cause the con- 
SFLDSP tents of the display to change. 


The SFLDSPCTL keyword 
must be in effect if an input 
operation is done to retrieve 
the status of a CFnn or CAnn 
key even if no fields are dis- 
played. 
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Table 4-1 (Page 2 of 5). Optional Functions for Subfiles 


Function 


DDS keyword 


Additional information 


Delete the subfile to allow 
another subfile to be used or to 
continue processing the display 
file with no subfile used 


Subfile delete 
(SFLDLT) 


Normally, subfiles should not 
be deleted by the program. 
When the file containing the 
subfile is closed, the subfile is 
deleted automatically by the 
system. However, if the file is 
shared and is still open by 
another program, the subfile is 
not deleted, and you must 
delete it in your program. You 
should only delete a subfile if 
the maximum number of sub- 
files are already being used 
and you need to use another 
one. The SFLDLT keyword is 
ignored if the subfile does not 
exist. 


Display a page of a subfile by 


Subfile record 


If CURSOR is specified for the 


a record number number SFLRCDNBR keyword, the 
(SFLRCDNBR) cursor is placed in the subfile 

record whose relative record 
number is identified by the 
contents of this field. The 
cursor is positioned at the first 
input-capable field in the 
subfile record. If there is no 
input-capable field, the cursor 
is positioned at the first output- 
only or constant field. 

Display a plus sign (+) in the Subfile end The plus sign is replaced by a 

lower corner at the extreme (SFLEND) or blank when the last record is 

right of the subfile display area (SFLEND(*PLUS)) displayed. An option indicator 

(page) when there are more must be specified with the 

records than fit on the display SFLEND or SFLEND(*PLUS) 
keyword. 

Display the word 'More...' on Subfile end The word 'More...' is replaced 

the line following the subfile SFLEND(*MORE) by the word 'Bottom' when the 

display area (page) when there last record is displayed. An 

are more records than fit on option indicator must be speci- 

the display fied with the SFLEND(*MORE) 
keyword. 

Display a scroll bar next to a Subfile end For more information, see 

subfile SFLEND(*SCRBAR) “Selection Lists—Overview” on 
page 6-24. 

Return the relative record Subfile scroll For more information, see 

number of the record at the top (SFLSCROLL) “Selection Lists—Overview” on 


of the current page of records 


page 6-24. 
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Table 4-1 (Page 3 of 5). Optional Functions for Subfiles 


Function DDS keyword Additional information 

Enable a command key to fold Subfile fold If the SFLFOLD keyword is 

or truncate records in a subfile (SFLFOLD) or subfile specified, the initial display of 
drop (SFLDROP) the records is folded. If the 


SFLDROP keyword is speci- 
fied, the initial display of the 
records is automatically trun- 
cated. Then the user can 
press the command key to 
display the truncated or folded 
version, respectively, of the 
subfile record. If the page size 
equals the subfile size or the 
subfile fits on one display line, 
the specified keyword 
(SFLFOLD or SFLDROP) is 
ignored. 


Both SFLFOLD and SFLDROP 
can be used on the same 
subfile. Optional indicators can 
be used on these keywords. 
The optional indicators are 
used to determine which mode 
the subfiles are initially dis- 
played in. If both keywords 
are optioned on or optioned 
off, then the subfile is initially 
displayed in folded mode. If 
the keyword is optioned off, the 
command key can still be used 
to display the truncated or 
folded version. 


Enable the Enter key as the Subfile enter If more than one subfile using 
Roll Up key and enable a (SFLENTER) SFLENTER is displayed at the 
command key to return to the same time, the only CAnn or 
high-level language program CFnn key in effect as an Enter 


key is the CAnn or CFnn key 
specified for SFLENTER on 
the most recently displayed 
subfile. The cursor position at 
the time the Enter key is 
pressed determines which 
subfile is affected. 
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Table 4-1 (Page 4 of 5). Optional Functions for Subfiles 


Function 


DDS keyword 


Additional information 


Initialize a subfile with no 
active records even though the 
subfile is active 


SFLINZ and subfile 
records not active 
(SFLRNA) 


A record becomes active when 
one of the following happens: 


e An output operation is 
issued to the subfile for a 
specific record. The record 
is not considered changed 
unless the SFLNXTCHG 
keyword is used. 

e A.user enters data into a 
displayed record. The 
record is considered active 
and changed. 


The records are displayed if 
the SFLDSP keyword is in 
effect. If default values were 
specified for fields in the 
records, they are included in 
the display. 


Initialize all records by the field 
descriptions in the subfile 
record format in the display file 


Return a record to the program 
when a get-next-changed oper- 
ation is performed 


SFLINZ 


Subfile next changed 
(SFLNXTCHG) 


When the SFLINZ keyword is 
in effect on an output operation 
to the subfile control record 
(SFLCTL), the system 
assumes that all option indica- 
tors on the subfile record are 
off; therefore, only those option 
indicators that are preceded by 
N are in effect. The subfile 
records are displayed if 
SFLDSP is in effect on an 
output operation. When the 
SFLINZ keyword is in effect on 
an output operation, the con- 
tents of input-capable fields 
without a default value are 
handled as follows: 


¢ Numeric fields are initial- 
ized to zeros. 

¢ Character fields are initial- 
ized to blanks. 

e Floating point fields are ini- 
tialized to nulls. 


The record is returned even if 
the record was not changed by 
the user 


Roll by a specified number of 
records instead of by page 


Subfile roll value 
(SFLROLVAL) 


This field must have the key- 
board shift attribute of signed 
numeric with zero decimal 
positions. It can be up to 4 
digits long and must be defined 
as an output/input or input-only 
field. 
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Table 4-1 (Page 5 of 5). Optional Functions for Subfiles 


Function 


DDS keyword 


Additional information 


Specify the number of spaces 
between each record on a line 
when more than one record is 
displayed on a line 


Subfile line (SFLLIN) 


This keyword is used for a hor- 
izontally displayed subfile. If 
the display file supports more 
than one screen size and the 
SFLLIN keyword is to apply to 
the secondary screen size in 
addition to the default (or 
primary) screen size, screen 
size condition names must be 
specified. 


Write a message to the 
message line on the display 
when your program does an 
output operation to the subfile 
control record 


Subfile message 
(SFLMSG) and 
subfile message ID 
(SFLMSGID) 


See the DDS Reference for 
more information about the 
message keywords. 


Determines where the cursor is 
located in a subfile 


Subfile cursor relative 
record number 
(SFLCSRRRN) 


The relative record number on 
which the cursor is positioned 
is returned in the hidden field 

specified as the parameter on 
the keyword. 


Specify cursor progression for 
a subfile 


Subfile cursor 
progression 
(SFLCSRPRG) 


The SFLCSRPRG keyword 
causes the cursor to move 
from a field in a subfile record 
to the same field in the next 
displayed subfile record. For 
more information, see “Defining 
Cursor Progression for Entry 
Fields” on page 2-17. 


Determines whether the subfile 
was in folded or truncated 
mode 


Subfile mode 
(SFLMODE) 


This is a required parameter 
and is only valid for subfile 
control records and the 
SFLCTL keyword must be 
specified. 


Define a single-choice 
selection list 


Subfile single-choice 
selection list 
(SFLSNGCHC) 


For more information, see 
“Selection Lists—Overview” on 
page 6-24. 


Define a multiple-choice 


Subfile multiple- 


For more information, see 


selection list choice selection list “Selection Lists—Overview” on 
(SFLMLTCHC) page 6-24. 

Control the availability of Subfile choice control For more information, see 

choices in a selection list (SFLCHCCTL) “Selection Lists—Overview” on 


page 6-24. 


Return all selected choices in a 
selection list using the get- 
next-changed operation 


Subfile return 
selected choice 
(SFLRTNSEL) 


For more information, see 
“Selection Lists—Overview” on 
page 6-24. 


The DDS keywords can be specified in any order; however, the subfile record 
format (SFL) must precede the subfile control record format (SFLCTL). 


You can use option indicators to condition many of the DDS subfile keywords. 
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You can specify a maximum of 512 subfiles in a display file, since the maximum 
number of record formats allowed in a display file is 1024. No more than 12 sub- 
files can be active at the same time to the same display station. One or more 
active subfiles can be displayed at the same time on the display station. A subfile 
must contain at least one field that can be displayed, and the subfile record format 
must not overlap the subfile control record format. If these records overlap, the 
display file cannot be created. 


All named fields in a subfile record, including fields that are not input-capable, are 
returned to the program. 


If any input data validity checking is specified for the subfile record, the validity 
checking is performed before any roll function is performed. If the data fails validity 
checking, the roll function is not performed. 


When the relative record number of the record written to the subfile equals the 
subfile size, the system sends the program a CPF5003 message indicating that the 
subfile is full. (Not all records need to be active; that is, this message is sent even 
if the only record written to the subfile was the last record in the subfile.) If the 
subfile size does not equal the page size and the program then writes more records 
to the subfile, the system automatically extends the subfile as additional records are 
added. The program is not notified that the subfile has been extended. (A subfile 
cannot be extended past 9999 records.) Also, if the subfile size equals the page 
size, the program is not notified that the subfile is full unless the last record written 
to the subfile occupies the last line available on the subfile display area. 


Processing of an extended subfile is less efficient because the extended space is 
not connected with the subfile. You can avoid extension by specifying a larger 
subfile size, but you will be wasting space if the extended space is used very 
seldom or never. 


Figure 4-1 on page 4-10 illustrates the order in which some of the DDS keywords 
used for subfile control are processed at run time: 
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Initialize Yes Initialize pa 
; play 
subfile i 
(SFLINZ) subfile Subhle 
_—_______—p} 
Subfile Yes Delete 
active Oh subfile 7 
al 
Shee Subfile Clear > 
aie active subfile 
ial 
Subfile Display | 
active subfile 
RSLH181-0 


Figure 4-1. DDS Keyword Processing Order for Subfile Control 


Using a Subfile in a Program 


To use a subfile, you perform the following basic operations in your high-level lan- 
guage program: 


1. Initialize the subfile. One way to initialize the subfile is to read records from a 
database file and write them to the subfile. Place the records in the subfile one 
at a time until the subfile is full or until there are no more records. 
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Program File 


Database ; Subfile 
File 


| —»[_ 1/0 Area | 


RV2W029-3 


2. Send the subfile to the display in one output operation using the subfile control 
record format. 


3. After the user reviews the records, changes them, or enters new records 
(depending on the function of the subfile), read the subfile control record 
format. 


Program File Display 
Subfile 


RV2W030-2 


4. Process each record in the subfile individually, updating the database file or 
writing new records to the database file as required. If the function of the 
subfile is to update records, the program need only process the changed 
records by using the READC operation in ILE RPG or the Read Subfile Next 
Modified verb in ILE COBOL. 


File 


Program 
Se Subfile 


— Data- 
—base 
— File 


<——_—_————_|_1/0 Area_}*——____ 
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A display file that uses subfiles may display only a portion of a subfile at a time. 
The portion that is displayed is called a subfile page. The data entered into an 
input-only field on a subfile display goes to the subfile when a function key (such as 
a Roll key) is pressed. The field then displays a value in the subfile, and what 
happens when the Enter key is pressed depends on the application code. 


Note: In a READC operation in ILE RPG, the data is moved from the subfile to 
the program. It does not remove it from the subfile, and it will continue to 
be displayed in the input-only field as if the fields were initialized to that 
value. Otherwise, it would appear that the subfile was empty when the data 
was actually there. 
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If the subfile is processed (for example, by an UPDAT operation in RPG), 
then the data is removed from the subfile, and the input-only fields are 
blanked out, reflecting the true condition of empty fields. This should be 
done after the READC operation moves the data to the program. 


Requesting I/O Operations for a Subfile 


An I/O request by a calling program to a subfile record format either writes a record 
to a subfile or reads a record from a subfile but never causes actual I/O to the 
display. To write subfile records to a display, the program must issue a request to 
the subfile control record format. 


The valid requests that can be made to a subfile depend on whether the request is 
made to the subfile record format or the subfile control record format. 


Requesting I/O Operations for a Subfile Record Format 


By requesting the correct I/O operation for a subfile record format, you can do the 
following: 


e Add a record (passed from a program) to a specified location in a subfile 

e Update an active record that already exists in the subfile 

e Read an active record at a specified location in the subfile 

e Read the next changed record in the subfile that is greater than the relative 
record number previously read with a get-relative or get-next-changed operation 


Adding a Record at a Specified Location in a Subfile 
The put-relative operation adds a record (passed from a program) at a specified 
location in a subfile. 


The location must be a valid relative record number in the subfile. The minimum 
relative record number is always 1. If the subfile size equals the subfile page, the 
maximum relative record number value is the subfile size value. If the subfile size 
is greater than the subfile page, the maximum relative record number value is 9999 
because the system automatically extends the subfile as required. In addition, the 
relative record number cannot be the number of an active record already in the 
subfile. The relative record number is ignored when field selection is specified for 
the subfile record. 


When a put-relative operation adds a record at the last record location (the subfile 
size value) in the subfile, a subfile-full condition occurs (message CPF5003). Both 
ILE RPG and ILE COBOL have special support for notifying the application 
program of this condition. See the appropriate high-level language manual. 


The contents of input-capable fields without a default value specified are handled 
as follows: 


e Numeric fields are initialized to zeros 
¢ Character fields are initialized to blanks 
e Floating point fields are initialized to nulls 
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Updating an Active Record in the Subfile 
The update operation updates an active record that already exists in the subfile. 


The active record must have been read before the update operation by a get 
request (either get relative or get-next-changed). No other I/O operations may be 
performed on the subfile to be updated between the read and the update. In addi- 
tion, the subfile being updated may not be displayed again between the read and 
the update (for example, using subfile roll or SFLDROP processing). 


Notes: 


1. Some high-level languages do not allow I/O to any format in the display file 
between the read and the update of a single subfile record in the display file. 
Refer to the documentation for the high-level language you are using for more 
information. 


2. If field selection is specified for the subfile record, only the fields that were 
selected when the record was placed in the subfile can be updated. Selecting 
different fields will cause results that cannot be predicted. 


Reading an Active Record at a Specified Location in the Subfile 
The get-relative operation reads an active record at a specified location in the 
subfile. 


The location must be a valid relative record number in the subfile. The entire 
record, including response indicators (defined at the file level and on fields in a 
subfile record), input, output, output/input, and hidden fields, is passed to the 
program, the relative record number is placed in the input/output feedback area, 
and the record is no longer identified as a changed record. Response indicators 
defined at the file level are always returned as off. Response indicators defined on 
fields in a subfile record, such as the BLANKS or CHANGE keywords, are returned 
as on or off depending on the information in the field at the time the get operation 
was done. 


If the record specified on the get-relative operation is not active, a not valid record 
number condition occurs (message CPF5020). This condition becomes a record- 
not-found condition in some high-level languages. See the appropriate high-level 
language manual. 


Notes: 


1. The get-relative operation and get-next-changed operation both update the rela- 
tive record number in the input/output feedback area. Subsequent get-next- 
changed-record requests retrieve sequentially changed records greater than 
this relative record number. 


2. The get-relative and get-next-changed operations do not process input data for 
overlapping fields in a subfile. The record returned to the program contains the 
data already existing in the buffer prior to the read operation for overlapped 
fields. If this is a problem, use the subfile initialize function to ensure all subfile 
fields are cleared. 
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Reading the Next Changed Record in a Subfile 

The get-next-changed operation reads the next changed record in the subfile that 
is greater than the relative record number previously read with a get-relative or get- 
next-changed operation. 


If the get-next-changed operation is used as the first read operation, the first 
changed record in the subfile is read. The entire record, including response indica- 
tors (defined at the file level and on fields in a subfile record), input, output, 
output/input, and hidden fields, is passed to the program, the relative record 
number is placed in the data management feedback area, and the record is reset to 
a not changed record. Response indicators defined at the file level are always 
returned as off. Response indicators defined on fields in a subfile record, such as 
the BLANKS or CHANGE keywords, are returned as on or off depending on the 
information in the fields at the time the get operation was done. 


If there are no more changed records in the subfile, a message (CPF5037) indi- 
cating that the last changed record has already been retrieved, is sent to the 
program. See the appropriate high-level language manual for a description of how 
this condition is reported to your program. 


If a record retrieved by a get-next-changed operation is updated and the 
SFLNXTCHG keyword is specified for an updated record, the updated record is set 
again as a changed record. This allows the program to ensure that the user has 
changed the record. For example, if the program detects an error in a record, it is 
advantageous to require the user to correct the error. The use of the SFLNXTCHG 
keyword allows the program to read that record again on a get-next-changed oper- 
ation so it can continue to reject the record until the error has been corrected. The 
next get-next-changed operation does not retrieve this updated record. The record 
cannot be retrieved again with a get-next-changed operation until all the changed 
records following it in the subfile have been processed. This is because the 
changed records are accessed sequentially and the sequence does not start at the 
beginning until after the message indicating that there are no more changed 
records in the subfile has been sent to the program. A get-next-changed operation 
following this message gets the first changed record in the subfile. Because no I/O 
operation has been issued to the display, any changed record would be a record 
that was processed using the SFLNXTCHG keyword. 


Notes: 


1. The get-relative operation and get-next-changed operation both update the rela- 
tive record number in the input/output feedback area. Subsequent get-next- 
changed-record requests retrieve sequentially changed records greater than 
this relative record number. 


2. The get-relative and get-next-changed operations do not process input data for 
overlapping fields in a subfile. The record returned to the program contains the 
data already existing in the buffer prior to the read operation for overlapped 
fields. If this is a problem, use the subfile initialize function to ensure all subfile 
fields are cleared. 
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Requesting I/O Operations for a Subfile Control Record Format 


By requesting the correct I/O operation for a subfile control record format, you can 
do the following: 


e Display subfile records 

e Place the subfile records on the display into the subfile for processing by the 
program 

¢ Display and process subfile records at the same time 


Displaying Subfile Records 
You can display subfile records by issuing a write operation to the subfile control 
record format. 


You can control the write operation using the following DDS keywords: 


SFLDSP Display the subfile. 

SFLDSPCTL Display the subfile control record. 

SFLCLR Clear the subfile of active records. 

SFLDLT Delete the subfile. 

SFLINZ Initialize the subfile with active records, or if the SFLRNA keyword 


is specified, with inactive records. When the subfile is initialized, all 

option indicators in the subfile record are assumed to be off. 
SFLEND Notify the user when the last available record is displayed. 
SFLRCDNBR Display the specified page of the subfile. 


Note: These keywords are described under “Describing Subfiles in Your DDS 
Source” on page 4-3. 


Placing Subfile Records on the Display for Processing 

A read operation must be issued to a displayed record format in order for the 
subfile records on the display to be placed into the subfile for processing by the 
program. The subfile records from the display are placed in their corresponding 
record positions in the subfile. 


Displaying and Processing Subfile Records at the Same Time 
The write-read operation is a single operation that combines the write and read 
operations and is more efficient than a single write operation followed by a single 
read operation. 


Recognizing Subfile I/O Requests in High-Level Languages 
Table 4-2 shows the I/O requests supported by the system and the equivalent 
high-level language operations: 


Table 4-2 (Page 1 of 2). Subfile Operations Supported by the System and Equivalent HLL Commands 


ILEC ILE RPG 
Operation Function Operation ILE COBOL Statement BASIC Statement 
Put Relative _Rwrited WRITE, WRITE SUBFILE WRITE REC = 
output specifi- 
cations 
Update _Rupdate UPDAT REWRITE SUBFILE REWRITE REC = 
Get Relative _Rreadd CHAIN READ SUBFILE READ REC = 
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Table 4-2 (Page 2 of 2). Subfile Operations Supported by the System and Equivalent HLL Commands 


ILEC ILE RPG 
Operation Function Operation ILE COBOL Statement BASIC Statement 
Get Next _Rreadnc READC READ SUBFILE NEXT MOD- READ MODIFIED 
Changed IFIED 
Write _Rwrite WRITE WRITE WRITE 
Read _Rread READ READ READ 
Write-Read _Rwriterd, EXFMT 

_Rformat, 

_Rpgmdev 


Controlling the Appearance of Subfiles 


Records in a subfile can be displayed either vertically or horizontally. In a vertically 
displayed subfile, a record is displayed on one or more lines, with each record 
beginning a new line (see Figure 4-2). In a horizontally displayed subfile, a record 
is complete on one line, and more than one record is displayed on a line (see 
Figure 4-3). You can specify that a subfile is to be displayed horizontally by using 
the SFLLIN keyword to define the number of spaces between each subfile record 
on a display line. Figure 4-4 on page 4-17 shows an example of a vertical subfile 
and a horizontal subfile being displayed at the same time. 


Record 1 
Record 2 
Record 3 
Record 4 


AAAS 
YvyYvV 


RSLH702-0 


Figure 4-2. Vertically Displayed Subfile 


= 
Record 1 Record 5 Record 9 
Record 2 Record 6 Record 10 
Record 3 Record 7 Record 11 
Record 4 Recor 8 Record 12 
(some otherrecord) 


RSLH703-0 


Figure 4-3. Horizontally Displayed Subfile 
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Figure 4-4. Horizontally and Vertically Displayed Subfiles Displayed at the Same Time 


If a subfile is larger than the space allowed for the subfile on the screen, the user 
can roll the display from one group of records in the subfile to another. Each group 
of records displayed at the same time is called a page. When you create a display 
file with a subfile, you must specify the size of the page for a subfile by specifying 
the number of records in the page (SFLPAG keyword). Usually page size is based 
on the number of lines available on the display. You must also specify the size of 
the subfile by specifying the number of records in the subfile (SFLSIZ keyword). 


Page size and subfile size can be the same; that is, all records in the subfile fit on 
one page. When page size equals subfile size, variable-length subfile records are 
supported. One record can take up only a single line while another record can take 
up more than one display line. Each record is placed in the first record position 
available in the subfile; this position is always a new line. In addition, the 
SFLDROP and SFLROLVAL keywords are ignored by display station support when 
page size equals subfile size. 


For more information on page size and subfile size, see “Specifying Subfile Size 
Equal to Page Size” on page 4-19 and “Specifying Subfile Size Not Equal to Page 
Size” on page 4-21. 


If records are to be displayed horizontally, the number of records to be displayed in 
a subfile (SFLPAG keyword) is adjusted so that the last line on the screen can be 
used to display a full line of records. For example, if the number of spaces 
between each record on a line (SFLLIN keyword) is specified such that six records 
fit on a line and 20 is specified for the page size (SFLPAG keyword), 20 is changed 
to 24, which is the nearest multiple of six. The number of records in the subfile 
(SFLSIZ keyword) is incremented by the same amount. 


Note: For the initial display of a subfile, the more records placed in a subfile 
before it is displayed, the slower the response time. 


Displaying Horizontal Subfiles with Display Modes 


You can use the display mode (DSPMOD) keyword to specify which of the two 
modes (or display sizes), 24x80 or 27x132, you want to use for your display 
station. 


When changing display modes, the display is cleared but the data is not cleared 
from the subfile. SFLDSP or SFLDSPCTL must be in effect for DSPMOD to be 
active in the control record. 


The following example shows how to specify DSPMOD with subfiles: 
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| saat tiie eis Pee yl eee Fave Beds phe an dete Fee sib verttiom Oates sad vss 


A DSPSIZ(*DS4 *DS3) 
A R SFLR SFL 

A FLD1 8 0 

A FLD2 7 I 1 16 

A FLD3 7 B 1 24 

A R SFLCTLR SFLCTL(SFLR) 
A SFLDSP 

A SFLDSPCTL 

A SFLSIZ(60) 

A SFLPAG(12) 

A SFLLIN(4) 

A *DS3 SFLLIN(6) 

A 02 SFLEND 

A 10 DSPMOD(*DS3) 
A 

A 


Figure 4-5. Sample DDS Using DSPMOD with Subfiles 


In the previous example, if the user's program turns indicator 10 off and issues a 
write-read operation to the subfile control record format (SFLCTLR), the subfile is 
displayed as follows: 


e In 27 by 132 (*DS4) mode, because indicator 10 for the DSPMOD keyword is 
off. 


Horizontally, because SFLLIN is specified. The SFLLIN value indicates the 
number of bytes between records. Because each record is 30 bytes long and 
the space between each record is 4 bytes long, four records can be displayed 
on one horizontal line, (4 x 30) + (3 x 4) = 132 bytes. The subfile is displayed 
on three lines because SFLPAG(12) is specified. 


The following example shows the subfile displayed in ~DS4 mode. 


RECORD 1 RECORD 4 RECORD 7 RECORD 10 
RECORD 2 RECORD 5 RECORD 8 RECORD 11 
RECORD 3 RECORD 6 RECORD 9 RECORD 12 


If the user presses the Enter key, control is returned to the user’s program. If the 
user’s program turns on indicator 10 and then issues another write-read operation 
to the subfile control record format (SFLCTLR), the subfile is displayed as follows: 


e In 24 by 80 (*DS3) mode, because indicator 10 for the DSPMOD keyword is 
on. 


¢ Horizontally, because SFLLIN is specified for the ~DS3 mode. If SFLLIN was 
not specified for the *DS3 mode, the subfile would have been displayed verti- 
cally. If the SFLLIN keyword is to be used for more than one screen size, a 
screen size condition name for each secondary screen size is required. 
Because each record is 30 bytes long and the space between each record is 6 
bytes long, two records can be displayed on one horizontal line, (2 x 30) + 6 = 
66 bytes). The subfile is displayed on six lines because SFLPAG(12) is speci- 
fied. To ensure other records are not erased, the SFLPAG may need to be 
specified for the secondary screen size. 
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The following example shows the subfile displayed in “~DS3 mode. 


RECORD 1 RECORD 7 
RECORD 2 RECORD 8 
RECORD 3 RECORD 9 
RECORD 4 RECORD 10 
RECORD 5 RECORD 11 
RECORD 6 RECORD 12 


Specifying Subfile Size Equal to Page Size 


You must specify the size of the subfile and the number of subfile records to be 
displayed at one time with the SFLSIZ and SFLPAG keywords. The use of subfile 
size equals page size is recommended when the number of subfile records to be 
displayed will fit on one page or when the number of records to be placed in the 
subfile is unknown and large. It is not an efficient use of resources to retrieve 
many database records to fill a large subfile if the user normally finds the needed 
information on the first page. 


When subfile size equals page size, the system does not automatically support the 
use of the Roll Up and Roll Down keys. If you want the user to roll through the 
subfile using these keys, you must specify the ROLLUP or ROLLDOWN keyword in 
the subfile control record, and your program must handle the roll up or roll down 
function. 


For example, if a subfile is used to allow the user to search through a long list, you 
can specify SFLSIZ equals SFLPAG and ROLLUP on the subfile control record: 


esPeteghs tg ck Pisses. ey eh casl eae lasts Suet poesOsewtet sca cT oun 
R SFLCTLR SFLCTL(SFLRCD) 

SFLSIZ(16) 

SFLPAG(16) 

ROLLUP(20 'Roll Up') 


Figure 4-6. Sample DDS Using SFLSIZ, SFLPAG, and ROLLUP Keywords 


When the user presses the Roll Up key, indicator 20 is set on and control returns to 
the program. In your program, you would: 


e Clear the subfile (a write operation to the subfile control record with the 
SFLCLR keyword in effect). 

e Use the indicator to control a return to the logic that fills the subfile with another 
page of records. 

e Display the new subfile page. 


You could also allow the display station user to press a CFnn key to return to the 
start of the search. When the user presses the CFnn key, the associated indicator 
is set on and control returns to the program. In your program, you would: 


e Clear the subfile. 

e Use the indicator to control a return to the logic that built the first subfile page 
based on the search code entered. (The program needs to keep the original 
search code in order to do this.) 
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Using the ROLLDOWN keyword when subfile size equals page size requires more 
lines of code in the program because the program must keep track of the record 
position in the subfile and in the database file. 


When the subfile size equals page size, you can use field selection and variable- 
length records in the subfile. If you use field selection, consider the following: 


e If the fields are selected through the use of option indicators, the relative record 
number is ignored and each record is placed in the first available record posi- 
tion in the subfile. 


e lf arecord is being updated, the field selection that does not match that on the 
original output is ignored. For example, assume that FIELD1 and FIELD2 are 
selected when the record is placed in the subfile. If the update selects FIELD2 
and FIELD3, fields would overlay the original FIELD1 and FIELD2 fields, and 
the results could not be predicted. 


¢ If field selection is specified on the subfile record, the number of records that 
can be displayed on the screen depends on the number of fields selected. 
When field selection is specified, the SFLPAG(value) keyword specifies the 
number of screen lines available to display the subfile record. In other cases, 
the SFLPAG(value) keyword specifies the number of subfile records that can 
be displayed at one time. 


e The SFLFOLD, SFLDROP, and SFLROLVAL keywords are ignored. 


When variable-length records are used, each record in the subfile is displayed 
beginning on the first available line on the page. If you use field selection for 
variable-length records, each record can take up a different number of lines on the 
display. Therefore, the number of records that actually fit in the subfile depends on 
the field selection of each record written to the subfile. The following shows an 
example of the DDS for a variable-length record: 


A R SFLRCD SFL 
A ITMNBR 8Y 0 6 2 
A ITMDSC 15 6 11 
A QTYOH 4 0 6 2 
A LSTPC 7 2 6 39 
A ALLOH 8Y 0 6 49 
A SLSMO 10 2 6 63 
A N80 SLSYR 122 7 7 
A N80 CSTYR 12 2 +3 


Figure 4-7. Sample DDS for a Variable-Length Record 


When indicator 80 is on, each record in the subfile fits on one line. However, when 
indicator 80 is off, each record uses two lines on the display. 


Another typical use of variable-length records is where two or more entirely different 
formats are used to make up one format. In this case, each field would be sepa- 
rately conditioned by option indicators so that one record format might use multiple 
lines while another format uses only one line. 
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Specifying Subfile Size Not Equal to Page Size 


Subfile size not equal to page size should be used when a finite number of records 
can be placed in the subfile and that number is small (for example, 50). The 
SFLSIZ keyword specifies the subfile size. The system allocates space to contain 
the subfile records based on the value specified for SFLSIZ. You should specify a 
value equal to the number of records that you normally have in the subfile. If your 
program places a record with a relative record number larger than the SFLSIZ 
value into the subfile, the system extends the subfile to contain it (up to a maximum 
of 9999 records). 


When the subfile size is not equal to the page size, the use of the Roll Up and Roll 
Down keys is automatically supported. 


To inform the user that there are more records in the subfile, use the SFLEND 
keyword on the subfile control record. When SFLEND is in effect (for example, the 
option indicator is on), a + (plus sign) is placed in the lower position to the extreme 
right of the screen on each page except the last page. On the last subfile page, 
the + is replaced with a blank. 


When the subfile size is not equal to page size, you can use the SFLROLVAL 
keyword to allow the user to enter a value to specify how many records should be 
rolled up or down when the appropriate key is pressed. If the SFLROLVAL 
keyword is not used, the subfile is rolled by the SFLPAG value except for subfiles 
using SFLFOLD or SFLDROP. If the SFLFOLD or SFLDROP keyword is used, 
more records are displayed than the SFLPAG value when records are displayed in 
the truncated format. For truncated records, the display rolls by the number of 
records displayed in the truncated format. When the SFLROLVAL keyword is used 
and the Roll Up key is pressed, the uppermost record number in the displayed 
subfile is added to the roll value to determine the new uppermost record number. If 
this value is greater than the last record in the subfile, the last full page of records 
is displayed. If the Roll Up key is pressed when the last subfile page is displayed 
and the roll value is not less than the page size value, an error message is issued. 
If the roll value is less than the page size value, the roll function is performed. 


Variable-length records and field selection cannot be used when the subfile size is 
not equal to the page size. 


A technique to improve performance when you are using a multiple page subfile is 
to write only one page of subfile records at a time but use the OS/400 support to 
roll through the subfile. To do this, you need to define the ROLLUP keyword in 
DDS with a response indicator and also use the SFLRCDNBR keyword. In your 
program, you would write the records needed to fill one subfile page and then 
display that page. When the user wants to see more records, he or she presses 
the Roll Up key. The program then writes another page of records to the subfile, 
places the relative record number of a record from the second page into the 
SFLRCDNBR field, and displays the record. 


The second page of subfile records is now displayed, and if the user presses the 
Roll Down key, the roll down is handled by the system. If the user presses the Roll 
Up key while the first page is displayed, the system will also handle the roll up. 

The program is notified only when the user attempts to roll up beyond the records 
currently in the subfile. The program would then handle any additional roll up 
requests in the same manner as for the second page. When you use this tech- 
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nique, the subfile appears to be more than one page because of the use of the roll 
keys. Yet, you can maintain good response time because the program only fills 
one subfile page before writing it to the display. 


Checking Validity on Subfile Data 


In addition to the DDS validity checking keywords (CHECK, COMP/CMP, RANGE, 
and VALUES), you can also do validity checking on subfile data in your program 
and require the user to correct the error. 


For example, assume that you are using a subfile for an order entry program and 
you want to check the item number field to be sure it is a valid order number. You 
also want to check the quantity ordered field to ensure there are enough items on 
hand to fill the order. To do this, you can use the SFLNXTCHG keyword on the 
subfile record (SFL) to allow your program to diagnose the errors and require the 
user to correct them. The following DDS shows an example of using the 
SFLNXTCHG keyword: 


| caste cedegety tee cereal toe Ue Pads elec ee feces Oe totan ca eeeteses Tacs 


A R ORDENTD 

A 1 30'ORDER ENTRY DISPLAY' 

A 3. 2'Enter customer number: ' 

A CUST 5 3 25 

A R SFLRCD SFL 

A 61 SFLNXTCHG 

A LINNBR 2 7 4 

A ITMNBR 5 B 7 9 

A 40 DSPATR(RI PC) 

A QTYORD 4 B 7 20 

A 35 DSPATR(RI PC) 

A R SFLCTLR SFLCTL(SFLRCD) 

A SFLSIZ(5) 

A SFLPAG(5) 

A 55 SFLDSP 

A 50 SFLDSPCTL 

A 30 SFLCLR 

A 10 SFLINZ 

A 40 SFLMSG('Item number not valid' 40) 
A 35 SFLMSG('Qty not available’ 35) 


Figure 4-8. Sample DDS Using the SFLNXTCHG Keyword 


When the program detects an error, it sets on the indicator that conditions the 
SFLNXTCHG keyword and issues a write operation to the subfile control record 
with the SFLDSP keyword in effect. The field in error is displayed in reverse 
image, and the cursor is positioned at that field. The associated error message is 
also displayed. The user then corrects the error. 


A decision you must make when using the SFLNXTCHG keyword is whether to 
allow the user to change the subfile fields that were not in error. If you do not want 
the display station user to change those fields you can protect them with the 
DSPATR(PR) keyword. For those fields you do not want changed, the 
DSPATR(PR) keyword must be in effect only when the SFLNXTCHG keyword is in 
effect. If you allow the user to change the fields, you can: 
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¢ Define hidden fields for those fields that are to be checked. 

e¢ Move the data originally entered by the user into the hidden fields when an 
error occurs on a subfile. 

¢ Compare the data in the hidden fields to the fields just read to identify which 
fields have been changed so you can update the records that have already 
been processed when the user makes the changes. 


Displaying Error Messages from Subfiles 


You can use a subfile to display messages for multiple errors. The messages to be 
placed in the subfile are on a program message queue. Each message written to 
the subfile is displayed on a separate line and is truncated, if necessary. Each 
message line contains an attribute character in position 1 that is displayed as a 
blank, followed by the message text. For the 24 by 80 display mode, 76 characters 
are displayed. For the 27 by 132 display mode, 128 characters are displayed. 
Because both the message identifier and the message data are available from the 
program message queue, message help and substitution text are supported for the 
messages placed in a message subfile. If the SFLMSGRCD keyword is specified, 
the SFLPGMQ and SFLMSGKEY keywords must also be specified. 


The following shows an example of the DDS for a message subfile: 


A R MSGSFL SFL 

A SFLMSGRCD (14) 
A MSGKEY SFLMSGKEY 

A PGMQ SFLPGMQ 

A R MSGCTL SFLCTL(MSGSFL) 
A SFLSIZ(8) 

A SFLPAG(8) 

A 50 SFLDSP 

A 55 SFLDSPCTL 

A 60 SFLINZ 

A PGMQ SFLPGMQ 

A NBR 4 OH SFLRCDNBR (CURSOR) 
A 


Figure 4-9. Sample DDS for a Message Subfile 


The SFLRCDNBR(CURSOR) keyword is used to position the cursor at the first dis- 
played character in the message subfile that is specified in the SFLRCDNBR field 
so the Roll Up and Roll Down keys will apply to the message subfile. 


For information on sending and receiving messages and on the program message 


queue, see the CL Programming book. Message subfiles are the only kind of sub- 
files supported for CL programs and for ILE C programs. 
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Positioning the Cursor on the Displayed Subfile 


The DSPATR(PC) keyword lets you position the cursor for each page of the subfile 
record that is displayed. Write and update operations can be used to control 
DSPATR(PC) for: 


¢ The initial display of subfile records. (A write or write-read operation to the 
subfile control record when the SFLDSP and SFLDSPCTL keywords are used.) 

¢ Subfile records displayed using a roll key or a fold or truncate key (SFLDROP 
or SFLFOLD keywords). 


Positioning the Cursor Initially 
The cursor is positioned by the first of the following conditions that applies: 


e¢ The CSRLOC keyword on the subfile control record. 

¢ The DSPATR(PC) keyword within the records being displayed. 

¢ The DSPATR(PC) keyword within a field in the subfile control record. 

¢ The SFLRCDNBR(CURSOR) keyword within the subfile control record. 

e If nothing is specified, the cursor is positioned at the first input-capable field on 
the display. 


Note: If the keyboard is unlocked prior to the output operation that displays the 
subfile, explicit cursor positioning is not performed. 


Use the keywords in the following order: 


e¢ The CSRLOC keyword can be used to position the cursor anywhere on the 
screen. 

¢ The DSPATR(PC) keyword can be used to position the cursor at any field in 
the first record displayed when the output operation specifies the SFLDSP 
keyword. 

¢ The DSPATR(PC) keyword can be used to position the cursor at any field of 
the subfile control record. 

¢ The SFLRCDNBR(CURSOR) keyword can be used to position the cursor at the 
first input-capable field of the record whose record number is used to select 
which page is to be displayed first. If no input fields exist, the cursor is posi- 
tioned at the first selected output field in that record. 

e If neither the DSPATR(PC) nor SFLRCDNBR(CURSOR) keyword is used, the 
cursor is positioned at the first input-capable field on the display. 


Positioning the Cursor When a Roll Key Is Used 


The positioning of the cursor when a roll key is used depends on whether the 
DSPATR(PC) keyword is used: 


e If the DSPATR(PC) keyword is not used, the cursor is positioned at the same 
location as when the roll key was pressed. 

e lf the DSPATR(PC) keyword is used, the cursor is positioned at the first field in 
the displayed subfile records with the DSPATR(PC) keyword in effect. 


The following example illustrates both and shows part of the DDS for a subfile in 
which records are displayed vertically. Customer number, name, address, city, and 
state are displayed. A user can change customer name, address, city, and state. 
Customer number cannot be changed; it is an output field only. The DSPATR(PC) 
keyword has been specified for the customer number field (CUST). Subfile size is 
21 and page size is 7. 
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R SUBFIL1 SFL 
TEXT('Subfile record') 
3DSPATR(PC) 
1OCHECK(LC) 
32CHECK (LC) 


CUST 5 
NAME 20 
ADDR 20 
CITY 20 54CHECK(LC) 
STATE 2 76 
R FILCTL1 SFLCTL(SUBFIL1) 
50 SFLDSPCTL 
55 SFLDSP 
SFLSIZ(21) 
SFLPAG(7) 
60 SFLCLR 
TEXT('Subfile control record') 
OVERLAY 
PROTECT 
CA03(98 ‘End of program') 
2'NUMBER' 
10'NAME' 
32'ADDRESS' 
54'CITY' 
76'STATE' 


wanww 
PREP A 


rFPrrrrrrrrrrrrrrrrrrrrs 


PP PY PH PP 


Figure 4-10. Sample DDS Using the DSPATR(PC) Keyword 


The initial display looks like this: 


Cursor 
~ 

NUM BER NAME ADDRESS Cily STATE 
41394 Sorensen and Walton 500 5th Avenue New York NY 
41395 Charland, Inc. 200 Madison Avenue New York NY 
41316 Anderson’s Electric 950 2nd Avenue Atlanta GA 
41397 Morem Motors 1300 Pine Street Atlanta GA 
41398 Polt Electronics 240 Walters Place Chicago IL 
41399 Clark’s TV 560 3rd Street Chicago IL 
41400 Jim’s Repair 700 4th Avenue Chicago IL 

XX 


RSLH709-0 


The first seven records in the subfile are displayed and the cursor is positioned 
under the customer number in the first record. The user moves the cursor to the 
third record, updates the address for that customer, and moves the cursor to the 
customer number of the fourth record: 
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Cursor Changed Field 


| NUMBER NAME ADDRESS CITY STATE 
41394 Sorensen and Walton \ 500 5th Avenue New York NY 
\41395 Charland, Inc. 200 Madison Avenue New York NY 
\41316 Anderson’s Electric 950 2nd Avenue Atlanta GA 
41397 Morem Motors 1300 Pine Street Atlanta GA 
41398 Polt Electronics 240 Walters Place Chicago IL 
41399 Clark’s TV 560 3rd Street Chicago IL 
41400 Jim’s Repair 700 4th Avenue Chicago IL 


RSLH183-0 


Now the user presses the Roll Up key to display the next seven records. The 
cursor is positioned under the customer number in the first record: 


Cursor 

NUMBER NAME ADDRESS Chy STATE 
41401 Adam’sHome Repair 121 Golden Circle Chicago IL 
41402 J ane’s Radio/TV 135 Ransam Drive St Paul MN 
41403 Advanced Electronics g09 8th Street St Paul MN 
41404 Riteway Repair 443 Westem Lane New York NY 
41405 Fixtures, Inc. 607 9th Avenue Chicago IL 
41406 Hall's Electric 200 Main Street St Paul MN 
41407 Electric House 903 East Place Atlanta GA 


RSLH184-0 


If the DSPATR(PC) keyword had not been specified and the user pressed the Roll 
Up key, the cursor would have been positioned at the fourth record under customer 
number: 
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Cursor 


NUMBER NAME ADDRESS CITy STATE 
41401 Adam’sHome Repair 121 Golden Circle Chicago IL 
41402 Jane’s Radio/TV 135 Ransam Drive S& Paul MN 
41403 Advanced Electronics 809 8th Street S& Paul MN 
41404 Riteway Repair 443 Western Lane New York NY 
41405 Fixtures, Inc. 607 9th Avenue Chicago IL 
41406 Hall’s Electric 200 Main Street S& Paul MN 
41407 Electric House 903 East Place Atlanta GA 


RSLH185-0 


Positioning the Cursor When a Fold or Truncate Key Is Used 


When you use the SFLFOLD or SFLDROP keyword to assign a CFnn or CAnn key, 
cursor positioning is handled the same way as described under “Positioning the 
Cursor When a Roll Key Is Used” on page 4-24. The cursor is positioned as speci- 
fied for all displayed records, including those folded. When you use the SFLFOLD 
or SFLDROP keyword to assign a CFnn or CAnn key, the cursor is positioned only 
for those fields displayed. Cursor positioning specifications for fields in the folded 
portion of the record are ignored. 


Positioning the Cursor and Rolling When Two or More Records Are 


Displayed 


When you display two or more records at the same time, the position of the cursor 
determines the action taken when the user presses a roll key, regardless of which 
record was written to the display last. 


The cursor can be positioned in the roll-enabled area of the display or in the area 
that is not roll-enabled of the display. A roll-enabled area is: 


e¢ A record without subfiles and with the ROLLUP/ROLLDOWN keyword in effect 

e¢ A subfile control record with the ROLLUP/ROLLDOWN keyword in effect 

e A roll-enabled subfile, which is an active subfile with subfile size greater than 
page size 

e An active subfile with subfile size equal to page size and the 
ROLLUP/ROLLDOWN keyword in effect for its subfile control record 


Based on the location of the cursor, the action taken when the user presses a roll 
key is as follows: 


e lf the cursor is positioned in the roll-enabled area at a roll-enabled subfile or at 
the subfile control record for a roll-enabled subfile, the subfile is rolled. If the 
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subfile is at the end of the subfile and the corresponding ROLLUP/ROLLDOWN 
keyword is not in effect, the end-of-subfile message is sent to the user. If the 
ROLLUP/ROLLDOWN keyword is in effect at the end of the subfile, control 
returns to the program. 


e lf the cursor is positioned in the roll-enabled area at a record without subfiles 
with the ROLLUP/ROLLDOWN keyword in effect, at a subfile control record 
with the ROLLUP/ROLLDOWN keyword in effect, or at an active subfile with 
subfile size equal to page size and the ROLLUP/ROLLDOWN keyword in effect 
for the subfile control record, control returns to the program. 


e If the cursor is not positioned in the roll-enabled area, the system attempts to 
find the uppermost roll-enabled area on the display and perform the action indi- 
cated, as listed previously. If there is no roll-enabled area on the display, the 
command-key-not-valid message is sent to the user. 


Note: Records that do not occupy display space (record formats with no fields, 
with hidden, program-to-system, or message fields only, or with the 
CLRL keyword specified and no input-capable fields; and message sub- 
files) are assumed to be at line 0. Therefore, these records are consid- 
ered to be uppermost on the display, and the system attempts to roll 
them first. 


The following examples illustrate what action is taken, based on the location of the 
cursor, when two records are displayed and the user presses a roll key. 


In the following example, control returns to the program if the corresponding 
ROLLUP/ROLLDOWN keyword is in effect. This occurs because the cursor is posi- 
tioned at a record without subfiles and with the ROLLUP/ROLLDOWN keyword in 


effect. 
a 

NUMBER NAME ADDRESS CITY SATE 

41394 Sorensen and Walton 500 5th Avenue New York NY 

41395 Charland, Inc. 200 Madison Avenue New York NY Subfile 

41316 Anderson's Electric 950 2nd Avenue Atlanta GA with 

41397 Morem Motors 1300 Pine Street Atlanta GA SFLSIZ> 

41398 Polt Electronics 240 Walters Place Chicago IL 4p SFLPAG 
Nonsubfile 

Enter next customer number” Record with 
ROLLUP/ 
ROLLDOWN 
in Effect 


NX S 
RV2W050-0 


Cursor 


In the following example, two subfiles with the subfile size greater than the page 
size and their control records are displayed. The user positions the cursor in the 
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bottom subfile control record. The bottom subfile is rolled because the cursor is 
in the roll-enabled area of the display. 


positioned at a roll-enabled subfile 


NUMBER NAME ADDRESS CITY SIATE 
41401 Adam’sHome Repair 121 Golden Circle Chicago IL 
41402 J ane’s Radio/TV 135 Ransam Drive S& Paul MN 
41403 Advanced Electronics 809 8th Street S& Paul MN 
41404 Riteway Repair 443 Westem Lane New York NY 
41405 Fixtures, Inc. 607 9th Avenue Chicago I+ 
ORDER ~ LINE TOTAL 
NUMBER NUMBER NUMBER DESCRIPITON QTY Price PRICE 
1401 35900 1 E35 Motor 10 15.00 150.00 
41401 35400 2 F60 Pump 25 20.00 500.00 
| RV2W051-0 
Cursor 


Subfile 1 
with 

SFLSIZ> 
SFLPAG 


Subfile 2 
with 

SFLSIZ> 
SFLPAG 


In the following example, a subfile with the subfile size equal to the page size and 
the ROLLUP/ROLLDOWN keyword in effect is written to the display first. A record 
without subfiles and without the ROLLUP/ROLLDOWN keyword in effect is then 
written to the display. If the cursor is positioned at either the subfile record or the 
second record, control returns to the program. 


Cursor 
UMBER NAME ADDRESS CITY STATE 
1394 Sorensen and Walton 500 5th Avenue New York NY 
41395 Charland, Inc. 200 Madison Avenue New York NY 
41316 Anderson's Electric 950 2nd Avenue Atlanta GA 
41397 Morem Motors 1300 Pine Street Atlanta GA 
41398 Polt Electronics 240 Walters Place Chicago IL as 


Enter next customer number: 


RV2W052-0 


Subfile 
with 
SFLSIZ> 
SFLPAG 


Nonsubfile 
Record without 
ROLLUP/ 
ROLLDOWN 
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In the following example, the first subfile has a subfile size greater than the page 
size but the ROLLUP/ROLLDOWN keyword is not specified. The second subfile 
has a subfile size equal to the page size but the ROLLUP/ROLLDOWN keyword is 
not specified. If the cursor is positioned at the second subfile, the first subfile is 
rolled. In this position, the cursor is not in a roll-enabled area; therefore, the 
system finds the uppermost roll-enabled area in the display and performs the roll 


function. 
NUMBER NAME ADDRESS CITy SITE 
: : : Subfile with 
41401 Adam’sHome Repair 121 Golden Circle Chicago IL SFLSIZ> 
41402 J ane’s Radio/TV 135 Ransam Drive St Paul MN SFLPAG 
41403 Advanced Electronics g09 8th Street St Paul MN and without 
41404 Riteway Repair 443 Westem Lane New York NY | ROLLUP/ 
41405 Fixtures, Inc. 607 9th Avenue Chicago IL 4: J) ROLLDOWN 
ORDER LINE TOTAL : . 
NUMBER NUMBER NUMBER DESCRIPITON QTY Price PRICE . Subfile with 
7 SFLSIZ= 
41401 = 35900 1 E35 Motor 10 15.00 150.00 J SFLPAG 
41401 35400 2 F60 Pump 25 20.00 500.00 and without 
ROLLUP/ 
ROLLDOWN 


RV2W053-1 
Cursor 


In the following example, the subfile with a subfile size greater than the page size 
and without ROLLUP/ROLLDOWN keyword is written to the display first. The 
record without subfiles and with ROLLUP/ROLLDOWN keyword in effect is then 
written to the display above the subfile. If the cursor is positioned within the subfile 
record, the subfile is rolled. If the cursor is not positioned within the subfile record, 
the subfile is not rolled and control returns to the program. 
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Identifiers Highlight Command Prompt Exit Help 


Select a Router identifier and press Enter. 


Top-of-File 
RTYP CMGR 


Bottom-of-File RTYP_ Type of router. 


common user ID. 

RIDN Default system name. 
RMIN Name of Remote LU alias. 
LCLN Name of Local LU alias. 
MODN Mode name information. 


Enter Esc=Cancel Fl=Help 


RSLH054-0 


Understanding Subfile DDS and Program Logic-Example 


The following shows the DDS that describes the customer name search subfile 
shown earlier in this section. The DDS is followed by a description of the logic a 
program would use to process this subfile. 
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| sattiewel eso pend levee te ont d os eae welds coteey cb levies Ovies tia saT eis 


Ax* DISPLAY CUS220D CUSTOMER NAME SEARCH 

A CFQ3(99 ‘End of Program') 
A R NAMESR OVERLAY 

A 1 29'CUSTOMER NAME SEARCH' 
A 3 2'Search code' 

A SEARCH 5 I 3 15 

A R SUBFIL1 SFL 

A CUST 5 7 2 

A NAME 20 B 7 9 

A ADDR 20 B 7 31 

A CITY 20 B 7 53 

A STATE 2 B 775 

A R FILCTL SFLCTL(SUBFIL1) 

A 55 SFLDSPCTL 

A 50 SFLDSP 

A SFLSIZ(18) 

A SFLPAG(6) 

A 50 SFLEND 

A 60 SFLCLR 

A OVERLAY PROTECT 
A RCDNBR 2 OH SFLRCDNBR (CURSOR) 
A 45 5 2'NUMBER' 

A 45 5 9'NAME' 

A 45 5 31'ADDRESS' 

A 45 5 53'CITY' 

A 45 5 75'STATE' 


Figure 4-11. Sample DDS Showing Customer Name Search Subfile 


The following is an example of the logic a user program would use to process the 
subfile just shown. A write-read operation is a combined input and output opera- 

tion. A read is an input operation. A write is an output operation. See the appro- 
priate high-level language manual for the operations that can be performed in the 

high-level language program. 


User Program 


1. Opens a file and issues a write-read operation to the NAMESR record format to 
prompt for a search code. 


User 


2. Enters a zip code in the search code field. The program uses the search code 
field as a key field to find the first database record in the file with that key field. 
The program will build the subfile using that record as the first record in the 
subfile. 


User Program 


3. Obtains records (read operation) from the database file and places (write oper- 
ation to SUBFIL1) them in the subfile one record at a time until the subfile is 
full or there are no more records to place in the subfile. 


4. When all records are in the subfile, issues a write-read operation to the subfile 
control record format (FILCTL) with the following: 


a. A + (plus sign) is displayed in the lower right corner of the screen when 
there are more records than fit on one subfile page. Because the indicator 
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for the SFLEND keyword is on, the system replaces the + with a blank 
when the last subfile page is displayed. 

b. The indicator for the SFLDSP keyword is on, so the first subfile page is 
displayed. 

c. The indicator for the SFLDSPCTL keyword is on, so the subfile control 
record is displayed. 

d. The SFLRCDNBR(CURSOR) keyword is specified for a field. The program 
placed a value of 1 in this field, so the subfile page that contains relative 
record number 1 is displayed first and the cursor is positioned at the first 
input field in that record. (If no input field exists, the cursor is positioned at 
the first selected output field or constant in that record.) 

e. The constant field (heading line) indicators are on, so the constants in the 

subfile control record are displayed. 

. The OVERLAY and PROTECT keywords are in effect in the subfile control 

record so that the prompt (NAMESR) can remain on the display without 
being changed. 


Sad 


User 


5. 


Updates displayed records, using the roll keys to display different subfile 
records as needed. Presses the Enter key after completing all updates to the 
subfile. 


User Program 


6. 


Completes the input portion of the write-read operation to the subfile control 
record format. In this example, the subfile control record does not contain any 
input fields. The input portion of the write-read operation allows the display 
station user to enter data into the subfile. 


. Issues the get-next-changed operation to the subfile record to process the first 


subfile record changed by the user. 


8. Uses each changed record to update the corresponding database file record. 


10. 


11. 


12. 


. Repeats steps 7 and 8 until a no-more-modified-records condition exists for 


step 7. When this condition is detected, step 10 is performed. 


Issues a write-read operation to the prompt (NAMESR) to determine if the 
program should end or display another group of database records. The 
OVERLAY keyword is specified, so that the current display contents for the 
subfile are left unchanged. If the user presses the CF1 key, which turns on 
response indicator 99, the program will close the display file and end. If the 
user enters another search code for another group of records to be displayed, 
step 11 is performed. 


Issues a write operation to the subfile control record (FILCTL) with the fol- 
lowing: 


a. The indicator for the SFLCLR keyword is on, so the subfile is cleared of all 
records (the display is unchanged). 

b. The indicator for the SFLDSP keyword is off, so the contents of the display 
remains unchanged. 

c. The indicator for the SFLDSPCTL keyword is off, so the subfile control 
record is not displayed again. 


Repeats steps 3 through 10. The subfile was cleared (SFLCLR keyword) in 
step 11 so that new records can be placed in the subfile. The write operation 
to the subfile control record in step 4 has the constant field indicator off so that 
heading information is not sent to the display again. As long as the subfile 
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control record remains on the display (no intervening write operations without 
the OVERLAY keyword in effect have been performed), the fields do not have 
to be sent to the display again. 
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Chapter 5. Defining Windows with Display Files 


This chapter explains how to use the specialized DDS window keywords to create 
windows in your applications. The DDS window keywords provide the simplest, 
most flexible method of creating windows for a variety of purposes. For example, 
they allow you to use subfiles to present data in windows, to have the system auto- 
matically save and restore the underlying display, and to position data in the 
window by referring to positions in the window itself instead of positions on the full 
screen. 


Use the DDS window keywords if your windows must use other DDS functions, 
such as subfiles, display attributes, validity checking, and optioning. Also use the 
DDS window keywords when the window contains multiple input fields, or if the 
window location can be varied. 


If you have help information defined with DDS and are using the HLPRCD keyword 
to display it, the WINDOW keyword can be used to easily display the information in 
a window. 


The following sections describe the terminology used for windows, the functions of 
the window keywords, and how to use the keywords for the following tasks: 


¢ Creating windows 

¢ Defining window borders 

e Reading data from windows 

¢ Changing window borders and contents 

e¢ Moving and duplicating windows 

e Making two windows seem active at one time 

e Making one window in a series stand out 

e Removing windows 

¢ Improving application performance by bypassing system save and restore oper- 
ations 


For examples on using the window keywords, see “Programming Examples” on 
page 5-15. 


For some applications, you might want to use a different method of creating 
windows: 


¢ Chapter 20, “Defining Online Help Information” on page 20-1 describes how to 
create help windows with the user interface manager (UIM). The UIM uses a 
different language from DDS. However, it automates many help window func- 
tions for you and provides a simple way of adding online help information to 
your existing applications. 


¢ The IBM WindowTool/400 PRPQ, SC41-0050, describes how to create 
windows with the WindowTool/400 PRPQ. Consider using this program if you 
use windows primarily to construct application menus. 


¢ Chapter 6, “Creating a Graphical Look for Displays” describes how to create 
menu bars, pull-down menus, selection fields, continued-entry fields, and how 
to use edit masks using DDS keywords. 
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Window Terminology 


A window is information that overlays part of the display. The user can view infor- 
mation inside the window and the portion of the display that is not overlayed by the 
window. However, only the window is active; the user cannot work with the under- 
lying display. When more than one window is displayed, only one window is active 
at a time. 


The active window is the window subject to the most recent input or output opera- 
tion. The active window appears to be the topmost window on the display. It is the 
only part of the display with which the work station user can interact. 


A window remains on the display until your application or the system takes action 
to remove it. Removing a window and overlaying a window are different oper- 
ations. When a window is removed, it no longer exists on the display, and you can 
no longer write to or read from it. When a window is overlayed by another 
window, it might not be visible to the work station user; however, it is still available 
for you to work with. 


DDS Window Keywords 


Four DDS keywords allow your applications to create and work with windows: 


WINDOW (Window) 
Creates a window on the display, changes the contents of an existing window, 
or makes an existing but inactive window active again. 


WDWBORDER (Window Border) 
Specifies the color, display attributes, and characters of a window border. 


WDWTITLE (Window Title) 
Specifies the text, color, and display attributes for a title of a window. The title 
is embedded in the top or bottom border of the window. 


Note: Not all controllers support text in the bottom border of windows, nor the 
left and right alignment of text in the top or bottom border. 


RMVWDW (Remove Window) 
Removes other windows from the display when a new window is displayed or 
when an existing window is redisplayed as the active window. 


USRRSTDSP (User Restore Display) 
Prevents the OS/400 system from automatically saving and restoring the under- 
lying display when windows are displayed and removed. In some situations, 
save and restore operations are unnecessary; bypassing them speeds up your 
application. You can also use the USRRSTDSP keyword to make an earlier 
window in a series pop up and overlay later windows, and to make two windows 
seem active at the same time. 


For detailed reference information about each keyword, see the DDS Reference. 
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Window Representation and Hardware Configuration 
Window borders appear differently, depending on the type of display station and 
work station controller you are using. 


For more information on how windows appear on different hardware configurations, 
see “Hardware Configuration” on page 6-1. 


Creating Windows 


The record-level keyword WINDOW allows a record format to be displayed inside a 
window. A maximum of 12 windows can be created on a display at one time. 


To create a window, write a record that specifies a WINDOW keyword. The first 
window record you write must be a window definition record specifying the window 
size and its location on the display. The window definition record places the 
window borders on the display. Then you can write the same window definition 
record again or use one or more window reference records to complete the specifi- 
cations for the window. 


Window Definition Records 


A window definition record is a record containing a WINDOW keyword that defines 
the window size and location. Size and location attributes include the position of 
the upper left corner of the window border and the number of rows and columns 
within the window. 


A window definition record must be the first record written for each window you 
display. It is the record that actually creates the window and makes it visible on the 
display. The record can contain the same types of fields or data found in any 
typical record. It can also contain a WOWBORDER keyword defining the window 
border. (The WOWBORDER keyword can also be used at the file level.) 


You can supply all the specifications for the window in the window definition record. 
You can supply additional specifications by writing the same window definition 
record again, as you would when displaying an error message in the window. You 
can also supply additional specifications by writing one or more window reference 
records after you write the window definition record. 


Window Reference Records 


Window reference records provide additional data to be placed in the window. 
They allow you to display more than one record format in a window. 


Each window reference record contains a WINDOW keyword specifying the name 
of the window definition record to which it applies. When the window reference 
record is written, the window definition record being referred to must be on the 
display. If the referenced record is not on the display, then a notify message 
stating that the window does not exist is returned to the application. 


Window reference records do not contain size and position attributes, and any 
active WOWBORDER keywords are ignored. 
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You can use as many window reference records as needed to complete the 
window. However, you do not need to write any window reference records to 
display a window. You can display a window using only a window definition record. 


Window Size and Location 
The following diagram shows the parts of a window that is created when a window 
definition record is displayed: 


Left border attribute 
Left border 
Leading window attribute 


First window column 
Last window column 
Right border attribute 
Right border 
Right continuation 


attribute 


Legh, ois seibzareieace emotes oele we Recs R «Top border 
L: AwwwwwwwwwwwwwwwwwwwB:R «First window row 
L: AWwwwwwwwwwwwwwwwwww. : 
L: AwwwwwwwwwwwwwwwwwwwB : 
L: AWwwwwwwwwwwwwwwwwww. : 
L: Awwwwwwwwwwwwwwwwwww. : 
L: AwwwwwwwwwwwwwwwwwwwB : 
L: AWwwwwwwwwwwwwwwwwww. : 
L: AWwwwwwwwwwwwwwwwwww. : 
L: Awwwwwwwwwwwwwwwwwww. : 
L: Awwwwwwwwwwwwwwwwwww. : 
L: AwwwwwwwwwwwwwwwwwwwB : 
L: AwwwwwwwwwwwwwwwwwwwB:R «Last window row 
L:AmmmmmmmmmmmmmmmmmmmB: R «Message line 

L: 

K 


DADDDDDADADAA D 


Key: 

L Left border attribute 

- Top and bottom border 

R Right continuation attribute 
Left and right border 
Leading window attribute 
Window area 

Message line 

Right border attribute 


weir. 


This window is specified as having a depth of 13 rows (also known as lines) and a 
width of 19 columns (also known as positions). The usable area inside the window 
borders is 12 rows deep and 19 columns wide. Row 13 is reserved for messages; 
it cannot contain fields. 


With its border, the window actually takes up additional rows and columns on the 
display. All windows take up two more rows, one each for the top and bottom 
borders. Most windows also take up six more columns: 


¢ Two for border attributes 

¢ Two for border characters 

¢ One for the leading window attribute 

¢ One for the continuation attribute on the right. 
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If a window starts and ends in the first and last columns of the full display, it takes 
up only four more columns instead of six. If a window row overlays DBCS fields, 
that row requires the six columns mentioned previously plus up to four more 
columns for DBCS shift-out and shift-in characters on each side. 


The window is positioned by the upper left corner of the border, which has a 
starting row position equal to the top border row and a starting column position 
equal to the left border column. Fields that do not fit within the window are diag- 
nosed during file compilation. If the SLNO keyword is used and specifies the 
starting line number, the DDS compiler flags any fields that do not fit within the 
window. If *VAR is specified on the SLNO keyword and the run-time starting line 
number does not allow the entire record to be displayed, an exception occurs. 


The DDS compiler diagnoses window location problems when either the upper left 
window line or upper left window position is specified as a constant. A run-time 
error occurs if a dynamically positioned window does not fit on the display. 


The special value, *DFT, can be specified in place of the start-line and start- 
position parameters on the window keyword. *DFT indicates that the system will 
determine the start line and start position of the window. The window is positioned 
relative to the cursor location. The system uses the following sequence of rules to 
position the window when *DFT is used: 


1. If the window will fit below the cursor position on the display, it is placed there. 
The top window border is positioned one row below the cursor. If possible, the 
left window border is positioned in the same column as the cursor; if not, the 
window is positioned as far to the left of the cursor as necessary for it to fit on 
the display. 


2. If the window will fit above the cursor position, it is placed there. The bottom 
window border is positioned one row above the cursor. The window is posi- 
tioned horizontally as described in step 1. 


3. If the window will fit to the right of the cursor position, it is placed there. The 
right window border is positioned in the next-to-last column of the display. If 
possible, the top window border is positioned in the same row as the cursor; if 
not, the window is positioned as far above that as necessary for it to fit on the 
display. 

4. If the window will fit to the left of the cursor position, it is placed there. The 


right window border is positioned two columns to the left of the cursor. The 
window is positioned vertically as described in step 3. 


5. If the window cannot be positioned in any of the above areas, it is placed in the 
bottom right corner of the display. 


Cursor Position 
To position the cursor in a window, use the CSRLOC and DSPATR(PC) keywords 
in the same way as for a full-screen display. The cursor is positioned with refer- 
ence to the upper left corner of the usable area of the window. 


If *RSTCSR is specified on the WINDOW keyword, and the cursor is moved 
outside the usable area of the active window, only the Print and Home command 
function (CF) keys are active. If the work station user presses any other command 
function (CF) key, the alarm sounds and the cursor is moved back to its position for 
the previous write operation. “RSTCSR is the default. 
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Note: On display stations attached to a controller that supports an enhanced inter- 
face for nonprogrammable work stations, the cursor can be moved out of a 
window only with a mouse when *RSTCSR is specified. 


If “NORSTCSR is specified on the WINDOW keyword, the user may move the 
cursor out of the active window and use any command function (CF) or command 
attention (CA) key. 


Error Messages 


Subfiles 


When windows exist on a display and *MSGLIN is specified on the WINDOW 
keyword for the window, any error messages are displayed on the last usable line 
of the active window. The last usable line in the window is reserved for error mes- 
sages; no records are displayed there. If the error message is longer than the line, 
it is truncated to fit. When windows exist on a display and *NOMSGLIN is specified 
on the WINDOW keyword for the window, any error messages are displayed at the 
bottom of the display or the location defined by the MSGLOC keyword. 


Help is available through the Help key for error messages displayed in windows. 


When messages reporting operational and keyboard errors, such as Function key 
not allowed, are displayed, the keyboard is locked and the user must press the 
Error Reset key to continue. 


An informational message, stating that mismatching shift-out and shift-in characters 
were sent to the display, is placed in the job log under the following circumstances: 


e The base display has a DBCS field that spans more than one line. 


¢ A window is displayed and part of the DBCS field from the base display is on 
the window message line. 


e A function key is pressed that results in an operational or keyboard error. 


A few message-related keywords function differently wnen used for windows: 


¢ The ERRSFL keyword is ignored. Its function is performed only when there are 
no windows on the display. 


¢ The MSGLOC keyword is ignored if *MSGLIN is specified on the WINDOW 
keyword. Its function is performed only when there are no windows on the 
display or when *“NOMSGLIN is specified on the WINDOW keyword. 


e Messages resulting from the ERRMSGID, ERRMSG, SFLMSG, SFLMSGID, 
and DDS validity-checking keywords are displayed in the window but do not 
lock the keyboard. Such messages do lock the keyboard when displayed on 
full-screen displays. 


A maximum of 24 subfiles can be active at any one time. A maximum of 12 sub- 
files can be displayed on the base display or in a single window at any one time. 


If a subfile is displayed in a window and the window is removed from the display, 
the subfile is not deleted. The subfile remains active until the display file is closed 
or you explicitly delete the subfile. 
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DDS Help Records 


If a window definition record is written to the display as a DDS help record, the 
current display is suspended as it normally is for application help, and the applica- 
tion help record is written to the display as a window. To avoid errors when using 
window records as help records, adhere to these requirements: 


¢ Include the ASSUME keyword in the display file containing the help record. If 
the ASSUME keyword is not present, the rest of the display is blank while the 
help window is displayed. 


e Use a value of *YES for the Restore Display (RSTDSP) parameter when cre- 
ating, changing, or overriding the display file. When returning from help, 
RSTDSP(*YES) restores the suspended display and puts the cursor back 
where it was when the Help key was pressed. 


e Use variable line and position values in your window definition record to allow 
the operating system to position the help window dynamically, according to 
cursor position. The system uses the same sequence of rules to position the 
window as if *DFT were specified on the window keyword. These rules are 
described in “Window Size and Location” on page 5-4. If the window definition 
record specifies that only the line value or only the position value is variable, 
the same rules are followed. However, the constant value is not changed. 


Defining Window Borders 


You can use the system defaults for your window borders or define them using the 
WDWBORDER keyword. This keyword specifies three border components: color, 
display attributes, and characters. More than one WOWBORDER keyword can be 
specified. You can use option indicators with the WOWBORDER keyword. 


You can use the WOWBORDER keyword at the file level, where it applies to each 
window definition record in the file, or on individual window definition records. If 
you use it on window reference records, a warning message is issued when the file 
is created. 


The following sections describe window border defaults, how the system handles 
multiple window border definitions, and how to use the WOWBORDER keyword to 
define UIM help window borders. 


Border Defaults 
When you do not use the WOWBORDER keyword, the system defaults are as 


follows: 

Border Element Default 

Color Blue on color displays. On noncolor display 
stations, this attribute is ignored. 

Display attribute Normal (that is, no attributes such as high- 
lighting or reverse image) 

Top and bottom border character Period (.) 

Left and right border character Colon (:) 

Top left and right corner character Period (.) 

Bottom left and right corner character Colon (:) 
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Note: RUMBA/400 work stations and InfoWindow* II display stations attached to a 
controller that supports an enhanced interface have solid-line window 
borders. For more information, see Table 6-1 on page 6-2. 


Multiple Border Definitions 


When the WOWBORDER keyword is specified at the file level and in a window 
definition record, the parameter values of the keyword at the file and record level 
are combined. If the parameter values conflict, the record-level parameter value is 
used. For example, if the following is specified at the file level: 


WDWBORDER((*COLOR RED) (*DSPATR RI)) 


and the following is specified at the record level: 


WINDOW(2 5 10 20) + 
WDWBORDER((*COLOR GRN) + 
CHCHAR: Tees sees ')) 


then the window border consists of green periods in reverse image. 


If more than one WOWBORDER keyword is specified at the same level, the param- 
eters for the keywords that are in effect are combined. If different values are speci- 
fied for the same parameter, the parameter value of the first keyword in effect is 
used. The values for individual components of the border are determined when a 
window definition record is written. The border values are determined by the fol- 
lowing hierarchy: 


1. Start with system defaults. 

2. Override the defaults with any file-level border specifications. 

3. Override any file-level border specifications with record-level border specifica- 
tions. 


The process is similar when more than one WOWBORDER keyword is in effect at 
the same level and the keywords specify the same WDWBORDER component 
(color, attribute, or character). The first component value is used. For example, 
assume that two WOWBORDER keywords are in effect at the file level: 


WOWBORDER((*COLOR GRN 
#CHAR '.....00. ')) 
WOWBORDER((*CHAR '---|||-|')) 


and the following is specified at the record level: 
WDWBORDER((*COLOR BLU) ) 


then the border component values are determined as follows: 


1. Start with the defaults for each component. 

2. Override the character component and color component defaults with the file- 
level values. Because the character component is specified more than once, 
use the first character component value specified. 

3. Override the file-level color value with the record-level value. 


The window border is constructed using the record-level border color, the first file- 
level border characters, and the default border display attributes. 


If a single WOWBORDER keyword does not specify all three border components, 
then those not specified use the values from any other WOWBORDER keywords in 
effect; they do not use the defaults. In the preceding example, this is demonstrated 
at the record level. Only the color component is specified. However, because the 
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character component is specified at the file level, the file-level value is used instead 
of the default. Because the display attribute component is not specified at the 
record or file level, the default is used. 


UIM Help Window Borders 


You can use the WOWBORDER keyword to specify the border attributes of help 
windows created with UIM panel groups. Assume that you are using DDS for full- 
screen displays and the UIM for help windows. If a window is on the display when 
the Help key is pressed, the UIM help window has the same borders as the DDS 
window. If no windows are active but the WOWBORDER keyword is specified at 
the file level or at the record level of a nonwindow record currently on the display, 
the system determines the border attribute and character values for the UIM help 
window by combining the file-level, record-level, and default values. Assume that 
no windows are currently displayed. First, a nonwindow record with the 
WDWBORDER keyword specified is written to the display. A UIM help window is 
then written to the display. The UIM help window borders use the attributes speci- 
fied in the WOWBORDER keyword on the nonwindow record. 


Defining a Window Title 


Use the window title (WDWTITLE) keyword to specify the text, color, and display 
attributes for a title of a window. The title is embedded in the top or bottom border 
of the window. The length of the title can be up to the number of positions speci- 
fied on the window-positions parameter specified on the associated window defi- 
nition keyword. 


Note: Some controllers do not support text in the bottom border of windows. 


The WDWTITLE keyword must be specified on a record that contains a WINDOW 
keyword (in the definition format). If a WINDOW keyword that refers to another 
window is also specified, a warning message is issued. 


Figure 5-1 shows an example of a window title. 


NONWINDOW DISPLAY RECORD 


WINDOW #1 
CUSTOMER NO. nnnnnn : 
NAME: 


ADDRESS: 
PHONE: 


F12=CANCEL 


F3=Xxxx F4=XXXXXXXX F6=XXXXX XXXXX F7=XXXxX F12=CANCEL 


— — 


Figure 5-1. Window Title—Display Example 
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DDS for a Window Title—Example 


lee F cated lyase coe eee ae oe 5 8 et eo tee ates sel eas 


A R RECORD1 WINDOW(6 15 18 51) 

A NO1 WOWTITLE((*TEXT &TTL1) (*COLOR GRN)) 
A 01 WOWTITLE((*TEXT &TTL1) (*COLOR RED)) 
A FIELD1 5A B 2 2 

A FIELD2 20A_ B 8 5 

A TTL1 10A OP 

Ax 

A R RECORD2 WINDOW(8 20 9 30) 

A WOWTITLE((*TEXT &TTL2) + 

A (*COLOR YLW) + 

A (*DSPATR RI)) 

A FIELD3 5A B 2 2 

A FIELD4 20A_ B 8 5 

A TTL2 10A OP 


Figure 5-2. DDS for a Window Title 


If the window defined by RECORD1 in Figure 5-2 is written to the display, the title 
will be whatever text is contained within the TTL1 field. The title will appear cen- 
tered in the top border of the window. If indicator 01 is set off, the text will be 
green. If indicator 01 is set on, the text will be red. 


If the window defined by RECORD2 is written to the display, the the title will be 
whatever text is contained within the TTL2 field. The title will appear centered in 
the top border of the window. The title will be in reverse image and yellow. 


Reading Data from Windows 


When windows are on the display, you can receive input only from the active 
window (that is, the last window written to the display). If your application reads a 
window record and the window exists on the display but is not the active window, 
then any windows subject to more recent input or output operations are removed. 
The window containing the record to be read is restored, becoming the active 
window. Then the record is read from the display. 


If your application attempts to read a window record and the window does not exist 
on the display, a notify message stating that the window does not exist is returned. 
If the application attempts to read a window record and the window is on the 
display but the record is not on the display, a message stating that the record is not 
on the display is returned. 


Changing Window Borders and Contents 


To change the contents of a window already on the display, you must write that 
window's window definition record or a window reference record specifying that 
window to the display. To change the borders of a window already on the display, 
you must write that window definition record to the display. 


If a window definition record is written to the display and a window with that name 


already exists on the display in the same position, a new window is not created. 
The new record is considered a normal write operation to the existing window. If 
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the new record specifies different border attributes or characters, the new attributes 
or characters are displayed when the record is written. 


Moving and Duplicating Windows 


If a window definition record is written to the display and a window with that name 
already exists on the display in a different position, a new window is created. The 
new window appears in the specified position and has the same name as the 
existing window. To move the window, use the RUVWDW keyword in the window 
definition record being written. The existing window with that name and any other 
windows on the display are removed when the new window is written. In effect, the 
window is moved. If you do not use the RMVWDW keyword, the same window 
appears on the display in two different positions. 


If a window reference record is written to the display and the specified window is on 
the display, the record is written to the most recently created window with the spec- 
ified name. To write to an earlier window with that name, use a window definition 
record specifying the earlier window's location. 


Making Two Windows Seem Active at Once 


Although only one window can be truly active at a time, you can make two windows 
appear to be active at once. You might use this to display two windows side by 
side and allow the work station user to switch back and forth between them. 


To make two windows appear active: 


1. Set up function keys to perform the switching action for the work station user. 
For example, you might provide one key to page through data in the first 
window and another key to page through data in the second window. 


2. Write the first window to the display. 


3. Write the second window to the display using the USRRSTDSP keyword. The 
USRRSTDSP keyword keeps the first window from being saved when the 
second window is displayed. It keeps the second window from being removed 
when the user returns to the first window and then keeps the first window from 
being removed when the user returns to the second. 


You can also use the USRRSTDSP keyword on the first window; it is not 
required on the first window because using it on the second window keeps the 
first window and all subsequent windows from being saved. 


4. Be prepared to rebuild each window when the work station user presses the 
keys that perform the switching action. Once the two windows are displayed, 
you must rebuild each window whenever the user wants to move to it. The 
USRRSTDSP keyword keeps both windows from being saved and restored, so 
they must be rebuilt at every switch. In effect, the system does not know that 
the previous window existed on the display. 


For more information about the USRRSTDSP keyword, see “Improving Application 
Performance” on page 5-13. 
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Making One Window in a Series Stand Out 


Assume that you display a series of windows that looks like this: 


| 


: | 


| 


Now you want to return to Window 3 and make it appear to pop out of the series, 
so that the display looks like this: 


| 


: | 


To make Window 3 stand out without removing Windows 4 and 5 from the display, 
take these steps: 


1. Specify the USRRSTDSP keyword on Window 4 or any earlier window (that is, 
Windows 1 through 3). The USRRSTDSP keyword prevents the previous 
window and any subsequent windows from being saved. 


2. Rebuild Window 3 so that it looks the way it did before Window 4 was first 
displayed. Because USRRSTDSP was used, the display was not saved when 
Window 4 was added to the display or at any later time. Thus, none of the 
windows are removed from the display, and Window 3 appears to pop out of 
the series. 


For more information about the USRRSTDSP keyword, see “Improving Application 
Performance” on page 5-13. 


Removing Windows 


When a window is removed, it no longer exists on the display, and you can no 
longer write to or read from it. The window keywords provide you with several 
different ways to remove windows. Which method you use depends on which 
windows you want to remove and which operation you want to perform next. The 
different methods are described in the following sections. 


5-12 Application Display Programming V4R1 


Removing All Windows 
Remove all the windows on a display in one of these ways: 


1. Write to a nonwindow record. This allows you to remove all existing windows 
without displaying a new window. 


2. Write to a window record that specifies the RMVWDW keyword. The 
RMVWDW keyword causes all other windows on the display to be removed 
when the specified window is displayed. If there are no other windows, the 
RMVWDW keyword is ignored, and no error is returned. 


Removing More Recent Windows 
To remove more recent windows that are overlaying the window you want to make 
active, read or write to the window you want to make active. Assume that Window 
3 exists on the display but is not the active window. Windows 4, 5, and 6 were 
subject to more recent write operations than Window 3; therefore, they overlay 
Window 3. To remove Windows 4, 5, and 6 so that Window 3 is visible and is the 
active window, read or write to Window 3. 


Improving Application Performance 


In some cases, you can improve application performance by using the 
USRRSTDSP keyword to prevent the operating system from saving and restoring 
the display. The following sections describe how the system performs the oper- 
ations, and how and when to use the USRRSTDSP keyword. 


System Save and Restore Operations 


If you do not use the USRRSTDSP keyword, the operating system automatically 
performs save and restore operations for your application. Before a window is dis- 
played, the system saves the display, including any windows not being removed. 
When windows are removed, the system restores the display. 


If a new window is being created on the display, the record that is active when the 
window is written is saved, and the entire display remains as background data. 
Then the new window becomes active. The saved record can be a window record 
or nonwindow record; the procedure is the same for both. 


If a window record is written to the display to change or redisplay an existing 
window, any more recent windows are removed without being saved, the target 
window is restored, the new record is written, and the window becomes active. 


If a nonwindow record is written to the display, any existing windows are removed 
without being saved, the new record is written to the initial display, and the display 
becomes active. 


Response Time 
The time needed for the system to perform save and restore operations depends 
on your communications setup and on the window being displayed. 


The slowest response time occurs during the read and save operations performed 
when the first window is added to a display. Assume that the window is of average 
size and complexity. If the work station is attached to the AS/400 system by a 
twinaxial, local area network (LAN), or other high-speed communications line, 
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response time is quick. If the work station is attached by a 2400-baud dedicated 
line, it takes approximately 10 seconds to complete the read and save operations 
and then display the window. If the line speed is increased to 9600 baud, it usually 
takes about 2.5 seconds. 


Other operations, such as saving the display before the second or third window is 
added, or restoring the display after windows are removed, take less time. 


For more information, including details about other window sizes, terminal types, 
and line speeds, consult your marketing representative. 


Bypassing System Save and Restore Operations 

You can use the USRRSTDSP keyword to bypass system save and restore pro- 
cessing and instead have your application rebuild the display only when necessary. 
This technique can improve system performance and response time for the user of 
the application. Consider using it when you display only one window at a time and 
the windows are in a different display file, or when you display a series of windows 
in which the user will not return to earlier windows, or when you want more than 
one window to seem active at one time. 


For example, under the following conditions, the system ordinarily performs two 
save operations: 


e Your application displays only one window at a time. 
e The display file is created with RSTDSP(*YES). 
e The first window record to overlay the display is located in a separate file. 


The first save operation is performed when the display file is suspended. The 
second save operation is performed because a window is being displayed. 
USRRSTDSP eliminates the second, unnecessary save operation. 


To bypass system save and restore processing, take these steps: 


1. Create your own procedure to rebuild the display after a window is removed. 
Be sure to include any data that the user enters and that must be redisplayed. 


2. Specify the record-level USRRSTDSP keyword on the window following the first 
window you do not want the system to save. The USRRSTDSP keyword 
keeps the system from performing save and restore operations. The 
USRRSTDSP keyword is allowed only on records containing the WINDOW 
keyword; it is ignored on the window reference record. 


Once the USRRSTDSP keyword is specified, it remains in effect, even if the 
option indicator is set off, until you read or write to either the initial, windowless 
display or the window that is two windows before the window on which the 
USRRSTDSP keyword was specified. 


Assume that six windows are on the display and the USRRSTDSP keyword 
was specified on the fourth. To turn off USRRSTDSP and have the system 
resume saving the display, you must write to the second window. As shown in 
the diagram, the system has saved only the first two windows: 
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1. Saved | 


2. Saved | 


3. Not saved | 


4. USRRSTDSP; not saved | 


5. Not saved | 


6. Not saved 


USRRSTDSP Keyword Processing and Interactions 

The USRRSTDSP keyword interacts with other keywords and window-related func- 
tions. Before using the keyword, you should understand the following (assume that 
the USRRSTDSP keyword is in effect): 


e lf a window record is written to a window that was saved (window 1 or 2 in the 
above example), the saved display is restored, the current record is written to 
the target window, and the target window becomes active. At this point, the 
USRRSTDSP keyword is no longer in effect. 


e If a window definition record is written to a window that was not saved (window 
3, 4, or 5 in the above example), it becomes a new window. It is merged with 
the previous display image and written to the display. No windows are 
removed. 


e If a window record is read from a window that was not saved (window 3, 4, or 5 
in the above example), an error message is returned to the application. 


e If the initial display has been saved and the application writes to a window 
record specifying the RMVWDW keyword, any existing windows are removed. 
The new window is displayed on top of the initial display. The new window is 
active, and USRRSTDSP is no longer in effect. 


e If the initial display is not saved and the application writes to a window record 
that specifies the RMVWDW keyword, all existing windows are removed. The 
new window is displayed on top of the initial display. The new window is 
active, and USRRSTDSP is still in effect. 


e If a nonwindow record is written to the display and USRRSTDSP is specified on 
the first window, then the window is not removed, and the nonwindow record 
may overlay all or part of the window. 


Programming Examples 


The following sections illustrate the basic functions of the window keywords. The 
first example shows how to use a variety of window functions. It defines a full- 
screen display and several windows in one display file. The second example 
shows how to create windows for a full-screen display defined in a separate display 
file. The third example shows how to simulate menu bar support. 
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Using Basic Window Functions 


The following scenario demonstrates the basic functions of the window keywords. 
The scenario is presented in three sections: 


¢ The DDS used to define a full-screen display and windows 
e¢ The RPG program used to display the full-screen display and windows 
¢ Discussion and illustration of the results 


DDS Full-Screen Display and Window Definitions 
The following DDS defines the initial display and two windows used in the scenario: 


Akece oa c ccc sesso esses cesses Sec e tt oer eee aces cease eo bec slS cesses Sece sees * 
Ax DISPLAY FILE - DEMOFM 

Akeseceeece ca cee cS ee meses eees eee Scceseecseeecetcceeccececcccseeccceeccecs * 
Vee ee eer eT Te CC eT ECCT OCTET COE CETL COTO oT oe * 
Ax FILE LEVEL KEYWORDS 

Aka SeeersassessescenaseseSsSsee si eet esses eecec ss escs sce pccct cass sce ceesees * 
A DSPSIZ(24 80 *DS3) 

A HELP 

Ax* 

Aken ceeee cetaceans eecccesesesceececeseecsece ect escececee cess cenescecccbce * 
Ax RECORDS USED IN DEFINING INITIAL DISPLAY 

Akeseoses eee ese seceee anes S cee wees se esse eee esate ss Ssee see ate esa see cee eens * 
A R INITIAL 

A CAQ3 (03) 

A CA04 (04) 

A CAQ6 (06) 

A CAQ7 (07) 

A CA12 (12) 

A CLRL(*ALL) 

A 3 28'NONWINDOW DISPLAY RECORD' 

A 6 1'FLD #1: 

A FLD48 30A B 6 9 

A 6 43'FLD #2:' 

A FLD49 15A B 651 

A 10 1'FLD #3:' 

A FLD50 30A B10 9 

A 10 43'FLD #4:' 

A FLD51 15A B10 51 

A 23. 1'F3=Xxxx' 

A 23 13'F4=Xxxxxxxx' 

A 23 29'F6=XxXxxx XxXxxx! 

A 23 48'F7=Xxxx' 


A 23 59'F12=CANCEL' 

A* 
Axostsctcccecsscesssiece cesses ae Sees ee coe ssi ceet ce cee sec tseseosSe sss lecsce * 
Ax RECORDS USED IN DEFINING WINDOW1 

Axes it ooss cc etes so hue ce shoe sae see oe oa eee soe eee eho ce eer ele * 
A R WINDOW1 WINDOW(7 3 11 33) 

A NO1 WDWBORDER((*COLOR GRN) ) 
A 01 WDWBORDER((*COLOR RED) ) 
A 2 13'WINDOW #1' 

A 4 2'CUSTOMER NO.' 

A FLD1 6A 0 4 15 

A 4 22';' 

Ax* 

A R REC2WIN1 WINDOW (WINDOW1) 

A OVERLAY 

A CA12 (12) 

A 10 2'F12=CANCEL' 

Ax* 

A R REC3WIN1 WINDOW (WINDOW1) 

A OVERLAY 

A 6 2'NAME:' 

A FLD2 24A B 6 8 

A 7 2'ADDRESS:' 

A FLD3 21A B 7 11 

A 8 2'PHONE: 

A FLD4 23A B 8 9 
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Ax* 

Akesec ioc osec sles see oes Soe ese oles ec eee loses See sooo ss See eee Sool 
Ax RECORDS USED IN DEFINING WINDOW2 

AxeseeSescscses eee sete ees c eee se se sees eee see oe ee ese ae ses see ses eee ese 
A R WINDOW2 WINDOW(9 25 11 32) 

Ax* 

A 2 12'WINDOW #2' 

A FLD5 22A 0 4 6 

A FLD6 254A 0 5 4 

A FLD7 254A 0 6 4 

A FLD8 254A 0 7 4 

Ax* 

A R REC2WIN2 WINDOW (WINDOW2) 

A OVERLAY 

A CA12 (12) 

A 10 8'XXxxxxx :' 

A FLD9 6A B 10 18 

Ax* 

A®esse-S nest eee eb eee eee eee eee ee eee eee eee eee ee ee eee eeee 


RPG Display Program 


This RPG program displays the full-screen display and windows defined in the pre- 


ceding section. Steps 1 through 5 are explained in the sections following the 


program. 


FRAKKKKRKRKRK RRR EKER RK RRR RR KER RRR RRR RRR RRR RRR RRR RRR RRR ERR RRR RERREREEE 
Fx RPG PROGRAM - WINDEMO 

FRARKAKRKKKR KKK KER KERR KERR RRR RR KERR KERR RRR RRR RRR RRR RR ER RRR ERE RERRERERE 
FDEMOFM CF E WORKSTN 

CR KK KRAKKR KR KK ER RRR RRR ER RRR RRR ERE RE RRR ER KER ERE RE RRR ERR RE RERERERERE 
Cx Step 1: Display Initial Display 

CR KK KA ARK RRR KEKE RE RRR ERR RE RRR ER RR ER RRR RRR ERE RE RRR ERR EREREREEERE 
C EXFMTINITIAL 

CR KR REAR RRR KEKE RRR RRR RR RE RRR ERR RE RRR ER KER ERE RE RRR ER ERE RERERRERERE 
Cx Step 2: Display Window #1 


CR R KK KAA KKAR RRR KERR RRR RRR EERE RRR ER ERE RRR ER KEKE RRR ERR E REE RERERREREERE 


C MOVE 'nnnnnn' FLD1 
C WRITEWINDOW1 
C WRITEREC2WIN1 
C EXFMTREC3WIN1 


CR KKK AA KK RRR REE RRR ERR KER RRR RRR ER ERE RRR ER KER ERE RE RRR ERR ERR ERERERE 
Cx Step 3: Display Window #2 

CR RRR KERR RRR KEKE RRR ER RRR RRR ERE RE RRR E RRR ERE RE RRR ER ERE RERERERERE 
C OVEL'Xxxxxxx 'TEMP16 16 

OVE 'xxxx x x'TEMP16 

OVELTEMP16 FLD5 

OVE 'xxxxxx' FLD5 


Q 


* 


OVEL'xxxxxx x'FLD6 
OVEL'xx xxxx 'TEMP16 
OVE 'xxx xxxx'TEMP16 
OVELTEMP16 TEMP17 17 
OVE ' ' TEMP17 
OVE TEMP17 FLD6 


* 


OVEL'xxxx xxx'FLD7 
OVEL'xxxx x x'TEMP16 
OVE 'x xxxx x'TEMP16 
OVELTEMP16 TEMP17 
OVE 'x' TEMP17 
OVE TEMP17 FLD7 


* 


OVEL'xxxxxxx 'FLD8& 
OVEL'xxxx xxx'TEMP16 
OVE 'xx xxxxx'TEMP16 
OVELTEMP16 TEMP17 
OVE '.' TEMP17 
OVE TEMP17 FLD8 


* 


WRITEWINDOW2 
EXFMTREC2WIN2 


CF 09-63: £9-°-CF 609-6 eee £9 Ce oe OD LDCs CRIS yes 29-8 


Chapter 5. Defining Windows with Display Files 


5-17 


Display Files, Examples 


CR RK RK AAR KEKE KR KEE RR KERR RRR RRR RRR KERR RE RRR ERR KERR RRR RR E RRR KE ERR RE RREREERE 


Cx Step 4: Restore Window #1 


CR RKRKA KKK RK RRR ERR KERR KR RRR KERR KER ERE RRR ERR KER ERE RRR ERE KER ERERRERERE 


C EXFMTREC3WIN1 


CR R KKK RAK KRK RRR ERR KERR RRR RRR ERR KERR RE RRR ERR KERR RE RRR ERR KERR RE RRREERE 


Cx Step 5: Display Initial Display 


CR R KKK AAR KEK RRR ERR KERR RRR RRR ERR KER RRR ERR RRR RRR RRR ERR REE ERE RREREERE 


C READ INITIAL 91 


CR R KKK RARER RRR ERR KERR RRR RRR ERR RRR RR E RRR ERR KERR REE RRR RR REE RE RREREERE 


Cx End The RPG Program 


CR R KKK AAR KEKE RRR ERR KER RRR RRR RRR KERR RRR ERR KERR RE RRR ERR REE RE RERERERE 


C SETON LR 


CR R KKK RAKE ERR E RR KERR KR RRR ERR KERR RE RRR ERR KERR RE RRR ERR RE RRR RREREERE 


Step 1: Display Initial Display 


The application creates the initial display without using a window keyword: 


(= = 
NONWINDOW DISPLAY RECORD 
FLD #1: FLD #2: 
FLD #3: FLD #4: 
F3=Xxxx F4=XXXXXXXX F6=XXXXXxX XXXXX F7=XXXX F12=CANCEL 


Step 2: Display Window 1 

The user types some data on the display and presses the Enter key. The applica- 
tion writes to window definition record WINDOW1, which creates the window. Then 
the application adds information to the window by writing to window reference 
record REC2WIN1 and performing a write/read operation to window reference 
record REC3WIN1. 


Before the window is displayed, the system performs a read screen immediate 
operation to obtain the display image and saves the underlying display. The 
system performs a read screen immediate operation only when the first window is 
added to the display. It performs a save operation each time a window is created. 
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ane 
NONWINDOW DISPLAY RECORD 
FLD #1: DATA ENTERED HERE FLD #2: DATA ENTERED 
: WINDOW #1 : 
Eee : FLD #4: DATA ENTERED 
: CUSTOMER NO. nnnnnn : : 
NAME: 
ADDRESS: 
PHONE: 
F12=CANCEL 
F3=Xxxx F4=XXXXXXXX F6=XXXXX XXXXX F7=XXXXxX F12=CANCEL 
— J 


Step 3: Display Window 2 

The user types some information and presses the Enter key. The application writes 
to window definition record WINDOW2. WINDOW2 is not the active window, and it 
is not currently on the display; therefore, the system saves the underlying display, 
associating the saved data with WINDOW1. Then a new window is created. The 
application adds information to the window by performing a write/read operation to 
window record REC2WIN2. 


(— sy 
NONWINDOW DISPLAY RECORD 
FLD #1: DATA ENTERED HERE FLD #2: DATA ENTERED 
WONDOW:. <‘sl-ses so. ssvelievove- labels 40.’ gieadereiis aca lste: @eat'ace uve sl yece a 
F ‘ : D 
CUSTOMER NO. nnnnn : WINDOW #2 
NAME: MY NAME : XXXXXXX XXXX X XXXXXXX 
ADDRESS: MY ADDRES : XXXXXX XXX XXXX XXX XXXX 
PHONE: MY PHONE : XXXX XXXXXXX X XX XXXX XX 
‘ XXXXXXX XXXX XXXXX XXXXX. 
F12=CANCEL 
i a een Aware 3 XXXXXXX ¢ 
F3=Xxxx F4=XXXXXXXX F6=XXXXX XXXXX F7=XXXXxX F12=CANCEL 
— —_ 


Step 4: Restore Window 1 

The user types some data and presses the Enter key. The application performs a 

write/read operation to window record REC3WIN1. The record format name speci- 
fied on the WINDOW keyword, WINDOW41, is not the active window. However, the 
window is currently on the display; therefore, the system restores the saved display 
associated with WINDOW1. The restore operation removes WINDOW2, which was 
written after WINDOW1. Then REC3WIN1 is written to the restored window. 
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(— — 
NONWINDOW DISPLAY RECORD 
FLD #1: DATA ENTERED HERE FLD #2: DATA ENTERED 
¢ WINDOW #1 : 
Fes : FLD #4: DATA ENTERED 
: CUSTOMER NO. nnnnnn : : 
NAME: MY NAME 
ADDRESS: MY ADDRESS 
PHONE: MY PHONE 
F12=CANCEL 
F3=Xxxx FA4=XXXXXXXX F6=XXXXX XXXXX F7=XXXXxX F12=CANCEL 
— ae 


Step 5: Display Initial Display 


The user presses the Enter key. The application performs a read operation to the 
initial display, which automatically removes the last window from the display. 


(— >) 
NONWINDOW DISPLAY RECORD 
FLD #1: DATA ENTERED HERE FLD #2: DATA ENTERED 
FLD #3: DATA ENTERED HERE FLD #4: DATA ENTERED 
F3=Xxxx F4=XXXXXXXX F6=XXXXX XXXXX F7=XXXx F12=CANCEL 


Defining Windows in a Separate Display File 


The following sections show the DDS code for a full-screen display and window 
and the procedural steps needed to use them. In contrast to the preceding 
example, this example keeps the window records in a separate display file from the 
file for the underlying display. This technique allows you to add windows for items, 
such as help, to existing applications, without rewriting the display-file code for the 


applications. 


In the example, the application uses RSTDSP(*NO) to indicate that a save opera- 
tion should not be done when a file is suspended. Because displaying a window 
also performs a save operation, using RSTDSP(*NO) prevents two save operations 
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from being performed. Because removing the window restores the screen that was 
present prior to the window operation, the application is not required to rebuild the 
display after window processing. For more information on the USRRSTDSP 
keyword, see the notes at the end of the example. 


DDS Full-Screen Display and Window Definitions 


Akane se ae cSee. Oaee eae cee ence tee nt oeecees ee eesti ecceee SoS ese cesses S * 
Ax DISPLAY FILE DISPLAY1 (RSTDSP=NO DFRWRT=*YES) 

Akeeeee ond ei See Set eck See ee ee ee eee Seton cee cee eee cect cee ee ees * 
A R REC1 

A 2 21'FIRST RECORD IN FILE' 

A 4 17'Current Customer #:' 

A FIELD1 6A B 4 38 

A* 

A R REC2 OVERLAY CA03(03) 

A 6 21'SECOND RECORD IN FILE' 

A 8 17'Current Customer #:' 

A FIELD2 6A B 8 39DSPATR(HI) 

A 24 02'CAQ3=EXIT' 

AxXeese teen Sete ce sete eee Stee eee eee Sees ec eee eee eee ete eee eee * 


RPG Program Source 
FDISPLAYICF E 


C WRITEREC1 

C WRITEREC2 

C RETRY TAG 

C READ REC2 90 
C 03 GOTO END 

C CALL 'WINPGM' 

C GOTO RETRY 

C END TAG 

C SETON LR 
Ax---------------------------- = ee ee ee * 
Ax DISPLAY FILE DISPLAY2 (RSTDSP=NO) 
AxkPececeeeSesceecieseeeesecenaeese nes sscnasssesoeccecceseesesssecnesees * 
A R WINDOW1 WINDOW(7 4 11 25) 

A NO1 WDWBORDER((*COLOR GRN) ) 

A 01 WDWBORDER((*COLOR RED) ) 

A 2 9'Window #1' 

A * 

A R REC2WIN1 WINDOW (WINDOW1) 

A CA12(12) OVERLAY 

A 4 1'Customer No. nnnnnn:' 

A 6 1'Name:' 

A FIELD3 198 B 6 7 

A 7 1'Address:' 

A FIELD4 16A B 7 10 

A 8 1'Phone:' 

A FIELD5 18A B 8 8 

A 10 1'F12=Cancel' 
Ax------------------------------- 5-5 ee ee ee ee * 
Ax Dummy record to remove window from display before returning 
Ax----------------------------- 5 ee ee = * 
A R RMVWDW CLRL(*NO) OVERLAY FRCDTA 

orc eee oe Te CCL COE TCC CLEC CCE CCC CL CCE CEE OCC CCE * 


Ax No I/0 will ever be done to this record. This record prevents the 
Ax display from clearing. 


Ax®eaoaSseu ose eee ek Set eee eee ee eee ce eek ee eee ee cette * 
A R DUMMY ASSUME 

A Ade Ae * 
Ax------------------------------ ee ee * 
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Display Files, Examples 


RPG Program Source for WINPGM 


FDISPLAYICF E 

WRITEWINDOW1 

EXFMTREC3WIN1 

WRITERMVWDW 

RETRN 

SETON LR 


QaAaAaAMNQAANg 


Step 1: Display Initial Display 
The application opens display file DISPLAY1, performs a write operation to record 
REC1, and performs a write/read operation to REC2. 


FIRST RECORD IN FILE 
Current Customer #: 
SECOND RECORD IN FILE 


Previous Customer #: 


— — 


Step 2: Display a Window 

The user enters data indicating that a window should be displayed. The application 
opens window display file DISPLAY2. This can be done from a separate program 
such as the one which displayed the screen in Step 1. The ASSUME keyword on 
record DUMMY keeps the full-screen display from being cleared, and the system 
marks display file DISPLAY2 as suspended. No I/O operation ever needs to be 
performed to record DUMMY; it only needs to be present in the file. 


The application performs a write operation to record WINDOW1. Display file 
DISPLAY1 is suspended; because of the RSTDSP(*NO) setting, no save is per- 
formed. Display file DISPLAY2 is restored; because of the RSTDSP(*NO) setting, 
no restore data is sent. 


The application performs a write operation to record REC2WIN1. 
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Display Files, Examples 


= = 
FIRST RECORD IN FILE 
Current Customer #: XXXXXx 
SECOND RECORD IN FILE 
#2 =~ XXXXXX 
Window #1 
: Customer No. nnnnnn: 
: Name: 
: Address: 
: Phone: 
: F12=Cancel 
Pie a 


Step 3: Return to the Initial Display 

The user enters data indicating that the application should return to the initial 
display file, DISPLAY1. The application performs a write operation to record 
RMVWDW, which causes the system to remove all windows from the display. 
Because the application does not close the DISPLAY2 display file, and the 
USRRSTDSP keyword is not specified, then removing the window restores the 
initial display. The application is not required to rebuild the initial display. The 
RMVWDW record should contain the FRCDTA keyword or specify DFRWRT(*NO) 
when the display file is created. 


The application performs a write operation to record REC1. Display file DISPLAY2 
is suspended; because of the RSTDSP(*NO) setting, no save operation is per- 
formed. Display file DISPLAY1 is restored; because of the RSTDSP(*NO) setting, 
no data is sent. 


The application performs a write/read operation to record REC2. 
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Display Files, Examples 


a 
FIRST RECORD IN FILE 
Current Customer #: 
SECOND RECORD IN FILE 
Previous Customer #: 
ea a 


Additional notes on this example: 


1. If the application closes DISPLAY2 in Step 3, then the application must rebuild 
the initial display by performing a write operation to REC1 and then a write/read 
operation to REC2. This can be avoided by specifying RSTDSP(*YES) for 
DISPLAY1. 


2. USRRSTDSP can be added to the window record in DISPLAY2. However, if 
this is done, the user must either specify RSTDSP(*YES) for DISPLAY1, or 
rebuild the initial display in Step 3. However, in Step 3, the application must 
still write RMVWDW, or the borders of the window are not displayed properly 
on the next write operation to the window. 

3. The KEEP keyword should be added to the window format both of the following 
conditions are true: 


¢ The application closes DISPLAY2 in Step 3. 


¢ No I/O is done to file DISPLAY1 prior to opening DISPLAY2 and displaying 
the window again. 
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Chapter 6. Creating a Graphical Look for Displays 


The graphical look is a change in what you see while you run DDS functions. 
Instead of dotted windows, you have crisp window borders. Instead of typing 
numbers in an option column to make a selection, you can use a mouse or mne- 
monics. A mnemonic is an underlined character within the text of a choice that 
you can type to select the choice. Instead of seeing option numbers, you can see 
radio buttons or check boxes. A radio button is a circle that precedes a choice in 
a single-choice selection field on a graphical display station. A check box is a 
square box that precedes a choice in a multiple-choice selection field on a graph- 
ical display station. You can click on radio buttons and check boxes to make 


choices. 
_14.Undo : © Yea 
2.Mark : aes oO ates 
7 nao 
3. Co q 
ve : O Mark 
Copy 


RV2W063-0 
Figure 6-1. Radio Buttons and Check Boxes 
In addition to a fresher look, the enhanced function includes menu bars and pull- 


down menus. Instead of having to simulate a menu bar by using lengthy DDS 
coding, you can use DDS keywords. 


Factors Affecting the Graphical Look 


The graphical functions described in this chapter appear differently, depending on 
the hardware configuration you have and the value you specify on the enhanced 
display (ENHDSP) parameter. 


Hardware Configuration 


Table 6-1 on page 6-2 and Table 6-2 on page 6-3 show how each graphical func- 
tion appears on different configurations. Letters A through F in the tables identify 
the configurations; these letters are referred to throughout this chapter. 
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Table 6-1. Functions Supported by Hardware Configurations A, B, and C 


Hardware Configuration 


A 


Cc 


Graphical User Inter- 
face (GUI) Program- 


InfoWindow II 
Display Station2 
Attached to Con- 


3477 Display Station 
Attached to Controller 


mable Work troller Supporting Supporting Enhanced 
Function Stations! Enhanced Interface3 Interface? 
Windows9 GUI4 windows and Character-based GUI5 Character windows and 


possible improvement 
in performance 


and possible improve- 
ment in performance 


possible improvement in 
performance 


Selection fields and 
menu bars 


GuI4 


Character-based GUI5 


Mnemonics, bar 
selection cursor 


Selection lists 


Bar selection cursor. 
Possible check boxes 
for multiple-choice 
lists. Possible radio 
buttons for single- 


Bar selection cursor. 
Possible check boxes 
for multiple-choice 
lists. Possible radio 
buttons for single- 


Bar selection cursor. 
Input field to the left of 
list. 


choice lists. choice lists. 
Continued-entry One field One field One field 
fields 
Edit masks Yes Yes Yes 
Highlighting Yes Yes Yes 
Cursor progression Yes Yes Yes 
Word spill Yes8 Yes Yes 
Simple hotspots Yes Yes No 
Scroll bars GUI 4 scroll bars Character-based GUI *MORE, *PLUS, or char- 
5 scroll bars acter scroll 
bars 6 
Push buttons Yes Yes Yes 
Auto-Selection Yes Yes Yes 
Auto-Enter Yes Yes Yes 
Programmable Yes8 Yes No 
Mouse Buttons 
Grid Lines” No No No 
Notes: 


1. For example, RUMBA/400 (Microsoft Windows** and OS/2*) and AlX* AS/400 Connection 
Program/6000 Release 2. 

2. InfoWindow II display stations: 3486, 3487, 3488. 

3. Twinaxial controllers: 5494 Release 1.1, and features 6050, 2661, 9146, and 9148. 

4. GUI includes solid-line window borders, selectable background colors, use of a pointer device (for 
example, a mouse), mnemonic selection, bar selection cursor, radio buttons (for single-choice 
selection fields), and check boxes (for multiple-choice selection fields). 

5. Character-based GUI is similar to GUI except that in character-based GUI, constructs are created 
using characters, and background colors are not selectable. 

6. Scroll bars that appear on display stations without pointing devices are for display purposes only. 

7. Grid lines are supported only on DBCS display stations. For the specific hardware required for grid 


lines, see “Hardware Requirements for Grid Line Structures” on page 6-82. 


8. RUMBA/400 does not currently support this function. 


o 
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. RUMBA/400 does not currently support window footers. 


Table 6-2. Functions Supported by Hardware Configurations D, E, and F 


Function 


Hardware Configuration 


D E F 
ASCII Display 
5250 Display Station Attached Any Display Station 


Station Attached 
to Controller Sup- 
porting Enhanced 
Interface! 


to ASCII Controller 
Supporting 
Enhanced Inter- 
face2 


Attached to Con- 
troller Not Sup- 
porting Enhanced 
Interfaces 


Windows’ 


Character windows 
and possible 
improvement in per- 
formance 


Character windows 
and possible 
improvement in per- 
formance 


Character windows 


Selection fields 
and menu bars 


Bar selection cursor 


Bar selection cursor 


Entry field driven 


Selection lists 


Bar selection 
cursor. Input field 
to the left of list. 


Bar selection 
cursor. Input field 
to the left of list. 


Input field to the left 
of list. 


Continued-entry One field One field Multiple fields 
fields 

Edit masks Yes Yes Ignored 
Highlighting Yes Yes Ignored 
Cursor Yes Yes Ignored 
progression 

Word spill6 Yes Yes Ignored 
Simple hotspots No No No 


Scroll bars *MORE, *PLUS, or *MORE, *PLUS, or *MORE, *PLUS, or 
character scroll bars character scroll bars character scroll 
4 4 bars 4 
Push buttons Yes Yes Yes 
Auto-Selection Yes Yes No 
Auto-Enter Yes Yes Yes 
Programmable No No No 
Mouse Buttons 
Grid Lines5 No No No 
Notes: 


1. Twinaxial controllers: 5494 Release 1.1, and features 6050, 2661, 9146, and 9148. 
2. ASCII controllers that support an enhanced interface: features 6041, 6141, 2637, 9145, 


9147. 


3. For example: 5250 display stations attached to 5294 and 5394 controllers or features 
2638, 6040, and 6140; some programmable work stations emulating a controller with an 
attached 5250 display station (for example, Client Access). 

4. Scroll bars that appear on display stations without pointing devices are for display pur- 


poses only. 


5. Grid lines are supported only on DBCS display stations. For the specific hardware 
required for grid lines, see “Hardware Requirements for Grid Line Structures” on 


page 6-82. 


[o>) 


. RUMBA/400 does not currently support this function. 


7. RUMBA/400 does not currently support window footers. 


Chapter 6. Creating a Graphical Look for Displays 6-3 


Enhanced Display Parameter 


The enhanced display (ENHDSP) parameter can be used with the CRTDSPF, 
CHGDSPF, and OVRDSPF commands. Use this parameter to specify whether the 
data being shown at a display station uses the enhanced capabilities available on 
the display station. 


Normally, DDS windows and CUA* graphical items are rendered using whatever 
enhanced capabilities are available on the display station. For example, window 
borders and menu-bar separators are presented graphically on a graphical display 
station. 


You can use ENHDSP(*NO) to cause all records defined in the display file to be 
displayed in character-based mode, regardless of the capabilities of the display 
station. When ENHDSP(*NO) is specified, none of the enhanced capabilities that 
may be available on a particular display station are used. That is, records display 
just as they would on a display station in configuration F in Table 6-2 on page 6-3. 


The default value for ENHDSP is *YES. Any enhanced capabilities of the display 
station are taken advantage of automatically. If you specify ENHDSP(*YES) and 
you use the default window border and menu-bar separator, the window border and 
the menu-bar separator appear as solid lines. If the display station is attached to a 
controller that does not support an enhanced interface for nonprogrammable work 
stations, ENHDSP(*YES) is ignored. The records in the display file are displayed 
on that display station in character-based mode (as if ENHDSP(*NO) were speci- 
fied). 


Writing records from files with ENHDSP(*YES) and files with ENHDSP(*NO) to 
the same display. lf the record (or records) displayed is from a file with 
ENHDSP(*YES), the first write operation of a record (such as a window) from a file 
with ENHDSP(*NO) causes all menu bars, pull-down menus, and other windows on 
the display to change from graphical to character-based. The records from the file 
with ENHDSP(*YES) are switched to the ENHDSP(*NO) mode of display. 


If the record displayed is from a file with ENHDSP(*NO), a write operation of a 
record (such as a window) from a file with ENHDSP(*YES) does not change the 
presentation of any menu bars, pull-down menus, or other windows on the display. 


Notes: 


1. The system file that is used for UIM help is shipped with ENHDSP(*NO)._ If you 
use UIM help with a file that has ENHDSP(*YES) specified, the display will 
changes from graphical to character-based. 


2. Some programmable work stations that support an enhanced interface ignore 
the window border and menu-bar separator keywords. 


3. If a window is written to the display station such that a border is in column 1, 
column 80 (for display size 24 by 80), or column 132 (for display size 27 by 
132), the window is always displayed as though ENHDSP(*NO) were specified. 
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DDS Keywords 


The tasks in this chapter refer to the DDS keywords, but may not provide all the 
details about them. For more information on each keyword, refer to the DDS Ref- 
erence. 


CCSID (Coded Character Set Identifier) 
Specifies that a “G” type field supports UCS-2 Level 1 data instead of 
DBCS-graphical data. 


CHCACCEL (Choice Accelerator Text) 
Specifies the text for the accelerator key on a single-choice selection field in a 
pull-down record. 


CHCAVAIL (Choice Color/Display Attribute when Available) 
Specifies the color or display attributes to be used when displaying the available 
choices in a menu bar or selection field. 

CHCCTL (Choice Control) 
Controls the availability of the choices for the field. 


CHCSLT (Choice Color/Display Attribute when Selected) 
Specifies the color or display attributes to be used when displaying a selected 
choice in a menu bar. 


CHCUNAVAIL (Choice Color/Display Attribute when Unavailable) 
Specifies the color or display attributes to be used when displaying the unavail- 
able choices in a selection field. 


CHOICE (Selection Field Choice) 
Defines a choice for a selection field. 


CNTFLD (Continued-Eniry Field) 
Defines a field as a continued-entry field. Continued-entry fields are sets of 
associated entry fields that are treated by the work station controller as a single- 
entry field during field data entry and editing. 

EDTMSK (Edit Mask) 
Defines an edit mask for fields with EDTCDE or EDTWRD keywords. 


ENTFLDATR (Entry-Field Attribute) 
Defines the leading attribute of the field that changes to a specified attribute 
whenever the cursor enters the field. When defined at both the field- and 
record-level, the field-level specification is used for the field. 


FLDCSRPRG (Cursor Progression Field) 
Defines the next field that the cursor moves to when exiting this field. 


GRDATR (Grid Line Attribute) 
Defines the color and line-type attributes for grid line structures in the file or 
record. 


GRDBOX (Grid Box) 
Defines the shape, positioning, and attributes of a box. 


GRDCLR (Grid Clear) 
Defines a rectangular area on a display within which all grid structures are 
erased. 


GRDLIN (Grid Line) 
Defines the shape, positioning, and attributes of a grid line. 
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GRDRCD (Grid Record) 
Specifies that this record defines grid structures. No other display fields are 
allowed on records with this keyword. 


HLPID (Help Identifier) 
Specifies an identifier for the constant in the help for a field. 


HTML (Hyper Text Markup Language) 
Specifies if a data stream is sent to an AS/400 5250 Workstation Gateway 
display, the HTML tags are sent along with the data stream. These HTML tags 
are processed on the HTML browser. This allows you to update applications to 
use on the Internet through the World Wide Web. 


MLTCHCELD (Multiple-Choice Selection Field) 
Defines a field as a multiple-choice selection field. A multiple-choice selection 
field is a field that contains a fixed number of choices from which a user can 
select multiple choices. 


MNUBAR (Menu Bar) 
Defines a menu bar. A menu bar is a horizontal list of choices that is followed 
by a separator line. 


MNUBARCHC (Menu-Bar Choice) 


Defines a choice for a menu-bar field. A menu-bar choice represents a group of 
related actions that the application user can select. 


MNUBARDSP (Menu-Bar Display) 
Displays the menu bar. 


MNUBARSEP (Menu-Bar Separator) 
Specifies the color, display attributes, or character used to form the menu-bar 
separator line. 


MNUBARSW (Menu-Bar Switch Key) 
Assigns a CA key to the Switch-to-menu-bar key. 


MNUCNL (Menu Cancel Key) 
Assigns a CA key to be the cancel key for menu bars or pull-down menus. 


MOUBTN (Programmable Mouse Button) 
Allows an attention indicator (AID) to be associated with various pointer device 
events. 


PSHBTNCHC (Push Button Choice) 
Defines a push button within a push button field. 


PSHBTNEFLD (Push Button Field) 
Defines a field as a push button field. A push button field is a field that contains 
a fixed number of push buttons. A push button is a button, labeled with text, 
graphics, or both that represents an action that starts when a user selects the 
push button. 


PULLDOWN (Pull-Down Menu) 
Defines a record as a pull-down menu for a menu bar. 


SFLCSRPRG (Subfile Cursor Progression) 
Causes the cursor to move to the same input field in the next subfile record 
when exiting this field. 


SFLCHCCTL (Subfile Choice Control) 
Controls the availability of the choices in a selection list. 
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SFLEND (Subfile End) 
Displays a plus sign (+) or text (More... or Bottom) in the lower right location of 
the subfile. It can also display a scroll bar. 


SFLMLTCHC (Subfile Multiple-Choice Selection List) 
Defines a subfile as a multiple-choice selection list. A multiple-choice 
selection list is a potentially scrollable list from which the user can select one 
or more items. 


SFLRCDNBR (Subfile Record Number) 
Displays the page of the subfile containing the record whose relative record 
number is in this field. 


SFLRTNSEL (Subfile Return Selected Choice) 
Returns all selected choices in a selection list using the get-next-changed oper- 
ation. 


SFLSCROLL (Subfile Scroll) 
Returns the relative record number of the subfile record that is at the top of the 
subfile when control is given to the application. 


SFLSIZ (Subfile Size) 
Specifies the number of records in the subfile. 


SFLSNGCHC (Subfile Single-Choice Selection List) 
Defines a subfile as a single-choice selection list. A single-choice selection 
list is a potentially scrollable list from which the user can select one item. 


SNGCHCELD (Single-Choice Selection Field) 
Defines a field as a single-choice selection field. A single-choice selection field 
is a field that contains a fixed number of choices from which a user can select 
one choice. 


Creating Menu 


Bars 


Figure 6-2 shows an example of a menu bar, which is a horizontal list of choices 
that appears at the top of a display. An optional menu-bar separator appears 
below the list. When you select a choice from the menu bar, a pull-down menu 
appears. A pull-down menu is a group of actions associated with a menu-bar 
choice. 


Edit View Options Help 


Figure 6-2. Example of a Menu Bar 


Defining the Menu-Bar Choices 


A menu bar is a special type of record containing a MNUBAR keyword and one 
menu-bar field. The menu-bar field is a numeric field containing one or more 
MNUBARCHC keywords. The MNUBARCHC keywords define the menu-bar 
choices and the pull-down menus associated with each choice. The menu bar 
always displays on the first line. The menu-bar record cannot contain any display- 
able fields other than the menu-bar field. 
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The number of rows occupied by the menu bar is determined by the number of 
choices, the maximum lengths of the choice text for all the menu-bar choices, and 
whether a menu-bar separator is specified. If you specify a menu-bar separator 
(the default), the number of rows the menu bar occupies (including the menu-bar 
separator) must be less than or equal to 12. If you do not specify a menu-bar 
separator, the number of rows the menu bar occupies must be less than or equal to 
11. It is not possible to extend the range of menu-bar choices to line 12. However, 
you can use line 12 for another record. 


If you define a pull-down record that is too large to fit beneath the maximum 
number of rows occupied by the menu bar, the file is not created. 


Suppressing the Menu-Bar Separator 
The default is for a menu-bar separator to display. To suppress the menu-bar sep- 
arator, specify MNUBAR(*“NOSEPARATOR). If you suppress the menu-bar sepa- 
rator, you cannot specify the menu-bar separator (MNUBARSEP) keyword. 


Defining the Menu-Bar Separator 
You can use the system defaults for the menu-bar separator or you can use the 
MNUBARSEP keyword. Using MNUBARSEP, you can specify the color and 
display attributes of the menu-bar separator and the character that makes up the 
separator. The default presentation of the menu-bar separator is a solid line on 
display stations in configurations A and B in Table 6-1 on page 6-2. The default 
character that makes up the menu-bar separator is an underline (_) on display 
stations in configuration C in Table 6-1 on page 6-2, and configurations D, E, and 
F in Table 6-2 on page 6-3. For an example of using the MNUBARSEP keyword, 
see Figure 6-3 on page 6-9. 


Note: The menu-bar separator is used as the top border of the pull-down menus. 
lts color does not change when a pull-down menu is displayed. To ensure 
a consistent appearance for your displays, use the same color and display 
attributes for both the menu-bar separator and the pull-down menu borders. 


Figure 6-3 on page 6-9 shows an example of the DDS for a menu bar. 
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lwucctos weds cwitheiou2ucevteanu des oct cowed eh ees vSany ins Ostet eed oes 
R MENUBAR MNUBAR 
MNUFLD 2Y 0B 1 2 
MNUBARCHC(1 PULLFILE + 
'>File ') 
02 MNUBARCHC(2 PULLEDIT + 
&EDITTXT) 
MNUBARCHC(3 PULLVIEW + 
‘>View ') 
04 MNUBARCHC(4 PULLOPT + 
'>Options 
&RTNFLD) 
MNUBARCHC(5 PULLHELP + 
'>Help ') 
MNUBARSEP((*COLOR WHT) ) 
EDITTXT 20A P 
RTNFLD 2Y OH 


rFrrrrrrrrrrrrrrrrrYrsts 


Figure 6-3. DDS for a Menu Bar. Assume that field EDITTXT contains the text >Edit. 


You can control which menu-bar choices are displayed by specifying option indica- 
tors on the MNUBARCHC keywords. Option indicators are used by the application 
program to specify if a menu-bar choice should be displayed (optioned on) or 
should not be displayed (optioned off). The DDS for option indicators are shown in 
Figure 6-3 on page 6-9. The application specifies the option indicators as on or off 
and then writes the menu-bar record (without MNUBARDSP in effect) to send the 
option indicators to the system. If a menu-bar choice is optioned off, the list of 
choices is compressed. However, the number of rows occupied by the menu-bar 
record is not compressed (because records cannot be variable length). The 
number of rows occupied by the menu bar is the number of rows needed if all the 
choices were displayed plus one row for the menu bar separator. If, through 
optioning, the list of choices is compressed so that it is displayed using fewer rows, 
the separator line is displayed on the line following the last row of choices. There 
are blank lines between the menu-bar separator and the next record on the display. 


The text which appears for each choice in a menu-bar comes from either the 
program-to-system fields named or the text specified for the choice text parameter 
of the MNUBARCHC keyword. The number of rows calculated by the system for 
the menu-bar record depends on the size of each program-to-system field or length 
of choice text. In addition, three spaces are assumed between each choice. Any 
trailing blanks in the choice text are removed; the remaining length is used for the 
calculation. The length of any program-to-system field is used as is, because 
trailing blanks can not be anticipated. However, when the menu-bar record is dis- 
played, any trailing blanks are removed. Therefore, the number of rows actually 
occupied could be less than the number calculated. When that occurs, blank lines 
appear between the menu-bar separator and the next record on the display. 


On display stations in configurations A and B from Table 6-1 on page 6-2, the 
menu bar looks like this: 
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L THER] «= Edit =View Options Help | 


Figure 6-4. Menu Bar on a Graphical Display Station with Enhanced Interface 


On display stations in configuration C from Table 6-1 on page 6-2, the menu bar 
looks like this: 


L GHEE] «Edit = View Options Help i 


Figure 6-5. Menu Bar on a Nongraphical Display Station with Underline Capability 


On display stations in configurations D and E from Table 6-2 on page 6-3, the 
menu bar looks like this: 


L GES 3Fdit View Options Help | 


Figure 6-6. Menu Bar on a Nongraphical Display Station without Underline Capability 


On display stations in configuration F from Table 6-2 on page 6-3, the menu bar 
looks like this: 


Figure 6-7. Menu Bar on a Display Station without Enhanced Interface 


Selection Fields—Overview 
There are two types of selection fields: single-choice and multiple-choice. 
Single-choice selection fields and multiple-choice selection fields contain a 
fixed group of choices displayed in a vertical or horizontal list. You can select any 


number of choices from the multiple-choice selection field. You can only make one 
choice from the single-choice selection field. 


On display stations in configurations A and B from Table 6-1 on page 6-2, the 
selection fields (vertical format) look like this: 
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Display Title 


Single selection field. ..: O One 
O Iwo 


O Three 


One 
Two 
Three 


Multiple selection field. ..: fF 


RV2W860-1 


Me 


Figure 6-8. Selection Fields on a Graphical Display Station with Enhanced Interface 
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On display stations in configuration C from Table 6-1 on page 6-2 and configura- 


tions D, E, and F from Table 6-2 on page 6-3, the selection fields (vertical format) 
look like this: 


Display Title 


Single selection field... : 


Multiple selection field ...: 


\ 


RV2W070-0 
Figure 6-9. Selection Fields on a Nongraphical Display Station 


DDS for Selection Fields—Example 


Figure 6-10 on page 6-13 shows an example of the DDS for both single-choice 
and multiple-choice selection fields. 


6-12 Application Display Programming V4R1 


lwucsthos weds owiehe oly. cow ease aes ott aged esebeen sSae ity .4s Ott eee? oes 
R RECORD 
2 30'Display Title' 
4 5'Single selection field... 
Fl 2Y OB 4 40SNGCHCFLD 
CHOICE(1 '>One') 
CHCCTL(1 &CTLONE1 MSG1111 QUSER/A) 
01 CHOICE(2 '>Two') 
CHCCTL(2 &CTLTWO1 &MSG1 &LIB/&MSGF) 
CHOICE(3 'T>hree') 
CHCCTL(3 &CTLTHR1) 


CTLONE1 1Y OH 
CTLTWO1 1Y OH 
CTLTHR1 1Y OH 
MSG1 7A P 
LIB 10A_ P 
MSGF 10A_ P 


8 5'Multiple selection field... :' 
F2 2Y OB 8 40MLTCHCFLD 

CHOICE(1 '>One') 

CHCCTL(1 &CTLONE2 MSG1112 QUSER/A) 
01 CHOICE(2 '>Two') 

CHCCTL(2 &CTLTWO2 &MSG2 &LIB/&MSGF) 

CHOICE(3 'T>hree') 

CHCCTL(3 &CTLTHR2) 


rFPrrrrrrrrrrrrrrrrrrrrrrrrrrsty 


CTLONE2 1Y OH 
CTLTWO2 1Y OH 
CTLTHR2 1Y OH 
MSG2 7A P 


Figure 6-10. DDS for Single-Choice and Multiple-Choice Selection Fields 


Creating a Vertical Single-Choice Selection Field 


You can define the number of choices and the selection numbers for each choice. 
On display stations in configurations A and B from Table 6-1 on page 6-2, the 
choices are preceded by radio buttons. This is true unless *NOSLTIND is specified 
on the SNGCHCFLD keyword. A blank line appears between choices that are not 
sequential. The location that you specify for the single-choice selection field is the 
location of the input field (on a character-based nongraphical display). On display 
stations in configurations A and B from Table 6-1 on page 6-2, the location you 
specify for the field is the location of the first radio button. 


Notes: 


1. If you suppress the selection indicators, the location that you specify for the 
single-choice selection field is the location of the first character in the first 
choice. 


2. If the single-choice selection field is within a pull-down menu, the location you 
specify is relative to the pull-down menu borders. 


A single-choice selection field is a numeric field containing a SNGCHCFLD keyword 
and one or more CHOICE keywords. The CHOICE keywords define the choices 
within the single-choice selection field. Figure 6-10 shows an example of the 
keywords to use. 
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You can have choice numbers up to two digits long. The maximum number you 
can specify for a choice is 99. On output, if the field contains a choice number, 
that choice is the default selection. 


The default is for vertical selection fields. You can create a horizontal selection 
field by using the *NUMCOL or *NUMROW values on the SNGCHCFLD keyword. 
See “Creating a Horizontal Selection Field” for more information. 


Creating a Vertical Multiple-Choice Selection Field 
A multiple-choice selection field is a special numeric field containing: 


¢ A MLTCHCFLD keyword to identify it as a multiple-choice selection field. When 
a user makes a selection, the field itself contains the number of choices that 
are selected. 

¢ One or more CHOICE keywords that define the choices. 

¢ A CHCCTL keyword for each choice to define a hidden field for each choice. 
The hidden field is used to indicate if the choice was selected. For more infor- 
mation on the CHCCTL keyword, see “Controlling the Availability of Choices” 
on page 6-36. 


The default is for vertical selection fields. You can create a horizontal selection 
field by using the *NUMCOL or *NUMROW values on the MLTCHCFLD keyword. 
See “Creating a Horizontal Selection Field” for more information. 


Creating a Horizontal Selection Field 


The default orientation for single-choice and multiple-choice selection fields is ver- 
tical. To specify a horizontal field, use the *NUMCOL or *“NUMROW values on the 
SNGCHCEFLD and MLTCHCFLD keywords. 


| wew Po vend ne ePeecn2eceatesee de ves Peus Ae vaste wer Se cov teds yOs costes cs Tesk 
A R RECORD 
A 2 2'Flavor...' 
A Fl 2Y OB 2 16SNGCHCFLD((*NUMCOL 2)) 
A CHOICE(1 ‘Chocolate ') 
A 01 CHOICE(2 ‘Strawberry ') 
A CHOICE(3 ‘Vanilla ') 
A CHOICE(4 'Peach ') 


Figure 6-11. Example of DDS for Horizontal Selection Field. The *NUMCOL 2 specifies that 
the field should display in two columns. 


The following shows how this single-choice selection field would appear on a 
character-based display, assuming option indicator 01 is on: 


Flavor... _ 1. Chocolate 2. Strawberry 
3. Vanilla 4. Peach 


The following shows how this single-choice selection field would appear if 
“NUMROW 2 were specified: 
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Flavor... _ 1. Chocolate 3. Vanilla 
2. Strawberry 4. Peach 


If the choices are nonsequential, no blank line or blank space is left for the omitted 
choice as would have happened with *“NUMCOL. 


You can optionally specify the number of spaces to appear between the choices by 
using the *GUTTER value on the SNGCHCFLD and MLTCHCFLD keywords. The 
gutter width must be at least 2. If “GUTTER is not specified, the default number of 
spaces between choices is 3. 


Note: The gutter width includes the beginning and ending attribute of the choices 
on either side of the gutter. 


The area occupied by the horizontal selection field is determined by the following: 
e The number of choices specified 
e The length of the longest choice 
e The width of the gutter 
e¢ The number of columns specified 


e The longest accelerator text specified (for a horizontal single-choice selection 
field in a pull-down menu) 


A horizontal selection field must fit within the minimum display size specified for the 
file (24 x 80 or 27 x 132). If the record is a window or a pull-down menu, the 
horizontal selection field must fit within the minimum window size. Other fields may 
be specified to the right or to the left of a horizontal selection field. Option indica- 
tors can be specified on horizontal selection fields, as they can for other fields. 


You can control which choices are displayed at one time by using option indicators 
on the CHOICE keywords. Unlike a vertical selection field, if a choice is optioned 
off, the remaining choices will be shifted to fill in the space. 


Cursor Movement in a Vertical Selection Field 
With *NORSTCSR on the SNGCHCFLD and MLTCHCEFLD keywords, the cursor 
keys move the cursor to the next cursorable choice in the direction of the key that 
is pressed. The cursor skips null choices and choices defined as noncursorable. 
The up arrow key moves the cursor up one choice. The down arrow key moves 
the cursor down one choice. If the cursor is on the top choice and the up arrow 
key is pressed, the cursor leaves the field. Likewise, if the cursor is on the bottom 
choice and the down arrow is pressed, the cursor leaves the field. If the cursor 
input only (CSRINPONLY) keyword is in effect, the cursor moves to the next 
cursorable item on the display above or below the current cursor position. The 
cursor left and right keys move the cursor one space to the left or right. 


Note: If the selection field is the only field defined within a pull-down menu, the 
cursor left and right keys close the present pull-down menu and open the 
next pull-down menu to the left or right. 


To keep the cursor within a selection field, use the ~RSTCSR value on the 
SNGCHCFLD and MLTCHCFLD keywords. If the cursor up key is pressed when 
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the cursor is on the top choice in the list, the cursor moves to the last choice in the 
list. If the cursor down key is pressed when the cursor is on the bottom choice in 
the list, the cursor moves to the top choice in the list. If the cursor left key is 
pressed the cursor moves up one choice. If the cursor is on the top choice, the 
cursor moves to the bottom choice. If the cursor right key is pressed the cursor 
moves down one choice. If the cursor is on the bottom choice, the cursor moves to 
the top choice. 


Note: If the selection field is the only field defined within a pull-down menu, the 
cursor left and right keys close the present pull-down menu and open the 
next pull-down menu to the left or right. 


Cursor Movement in a Horizontal Selection Field 


With *NORSTCSR on the SNGCHCFLD and MLTCHCEFLD keywords, the cursor 
keys move the cursor to the next cursorable choice in the direction of the key that 
is pressed. The cursor skips null choices and choices defined as noncursorable. If 
the cursor is on the top choice of any column in the field and the up arrow key is 
pressed, the cursor leaves the field. Likewise, if the cursor is on the bottom choice 
of any column in the field and the down arrow key is pressed, the cursor leaves the 
field. If the cursor input only (CSRINPONLY) keyword is in effect, the cursor 
moves to the next cursorable item on the display above or below the current cursor 
position. If the left arrow key is pressed and there is a cursorable item to the left of 
the current choice, the cursor moves to the choice. If there is no cursorable item to 
the left, the cursor leaves the field. If the right arrow key is pressed and there is a 
cursorable item to the right of the current choice, the cursor moves to the choice. If 
there is no cursorable item to the right, the cursor leaves the field. 


Note: 


To keep the cursor within a selection field, use the ~RSTCSR value on the 
SNGCHCFLD and MLTCHCFLD keywords. If the cursor up key is pressed when 
the cursor is on the top choice in any column in the field, the cursor moves to one 
of the following places: 


e lf there is a cursorable position in a column to the left, the cursor moves to the 
last choice in that column. 


e lf there is not a cursorable position in a column to the left or if there is no 
column to the left, the cursor moves to the last cursorable choice in right-most 
column in the field. 


If the cursor down key is pressed when the cursor is on the last choice in any 
column in the field, the cursor moves to one of the following places: 


e lf there is a cursorable position in a column to the right, the cursor moves to 
the top choice in that column. 


e lf there is not a cursorable position in a column to the right or if there is no 
column to the right, the cursor moves to the first cursorable choice in left-most 
column in the field. 


If the cursor left key is pressed and there is a cursorable choice to the left of the 
current choice, the cursor moves to that choice. If there is no cursorable choice to 
the left, the cursor moves to the first cursorable choice in the row above the 
present row (closest row, right-most choice). If the present row is the top row, the 
cursor moves to the right-most choice in the last row. 
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If the cursor right key is pressed and there is a cursorable choice to the right of the 
current choice, the cursor moves to that choice. If there is no cursorable choice to 
the right, the cursor moves to the first cursorable choice in the row below the 
present row (closest row, left-most choice). If the present row is the bottom row, 
the cursor moves to the left-most choice in the first row. 


Note: The cursor left and right keys will close the present pull-down menu and 
open the next pull-down menu to the left or right when the following are 
true: 


e The selection field is the only field defined within a pull-down menu 
e There is no cursorable choice to the left or right of the current choice 


Controlling the Selection Indicators in a Selection Field 


A selection indicator is an indicator that precedes a choice in a selection field or a 
selection list. It is used to select the choice or to show that a choice has been 
selected. An example of a selection indicator is a radio button. Radio buttons 
appear before choices in single-choice selection fields and single-choice selection 
lists. The default is for selection indicators to appear in selection fields. You can 
suppress the selection indicators in a selection field by specifying the *NOSLTIND 
parameter on the SNGCHCFLD and MLTCHCFLD keywords. 


The *NOSLTIND value is ignored for display stations that are not attached to a 
controller that supports an enhanced interface for nonprogrammable work stations. 
Figure 6-12 is an example of the DDS to suppress the selection indicators in a 
selection field. 


eee res Geert ner Seraree: SMe: Le Sone ERS. CO Pee Ce «eer, ey Ane 
R RECORD 
2 30'Display Title' 
4 5'Single selection field. . 
Fl 2Y OB 4 4OSNGCHCFLD(*NOSLTIND) 
CHOICE(1 '>One') 
01 CHOICE(2 '>Two') 
CHOICE(3 'T>hree') 
8 5'Multiple selection field. . 
F2 2Y @B 8 4OMLTCHCFLD(*NOSLTIND) 
CHOICE(1 '>One') 
01 CHOICE(2 '>Two') 
CHOICE(3 'T>hree') 


rFrrrrrrrrrTr,Tr 


Figure 6-12. DDS for Suppressing Selection Indicators in a Selection Field 


On display stations in configurations A and B from Table 6-1 on page 6-2, the 
selection fields look like this: 
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Display Title 


Single selection field... : Qne 


Iwo 
Three 


Multiple selection field . .. :Qne 
Iwo 
Three 


Ss 


RV3W067-0 


Figure 6-13. Suppressed Selection Indicators in Selection Field 


Creating Pull-Down Menus Using Single-Choice Selection Fields 


When you select a choice from the menu bar, a pull-down menu appears. A pull- 
down menu is a group of actions associated with a menu bar choice. Figure 6-14 
is an example. 


File Edit View Help *) 


O Undo 
O Mark 
© Copy 


RV2W859-1 


Figure 6-14. Example of a Pull-Down Menu 


You must define the pull-down menus and the corresponding menu bar in the same 
file. 


The last field in any pull-down menu always operates as though the CHECK(FE) 
(Field Exit) keyword were specified. This keeps the cursor in the pull-down menu 
after you enter the input that is in the last field in the pull-down menu. Then, if you 
press the Field Exit key with the cursor in the last field, the field is cleared and the 
cursor moves to the next pull-down menu. If the last field did not operate with 
CHECK(FE), the cursor automatically moves on to the next pull-down menu after 
you press the Enter key. 


A pull-down record can contain anything that a window record can contain. 
However, use only single-choice selection fields or multiple-choice selection fields 
in a pull-down menu. If you use fields other than single-choice selection fields or 
multiple-choice selection fields, the cursor does not move consistently on all display 
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stations. On display stations attached to a controller that supports an enhanced 
interface for nonprogrammable work stations, the cursor-right keys and cursor-left 
keys display the next pull-down menu when both of these conditions are true: 


e There is only one selection field in the displayed pull-down menu, and 
e The cursor is positioned on the selection field. 


On display stations attached to a controller that does not support an enhanced 
interface for nonprogrammable work stations, the cursor movement keys move the 
cursor one character position within the pull-down menu. 


Figure 6-15 is an example of the DDS for a pull-down menu. The figures that 
follow show how the pull-down menu appears on each type of display. 


Note: Assume that the record PULLDOWN is specified on the MNUBARCHC 
keyword for the Edit choice, and that the MARKTXT field contains the text, 


>Mark. 

levabeneulvakateenteer gi twonvaenaviwisG4iatct ves cBvcd Paani Paveehiceelaxt 

A R PULLDOWN PULLDOWN 

A Fl 2Y 0B 1  1SNGCHCFLD 

A 01 CHOICE(1 '>Undo ') 

A CHOICE(2 &MARKTXT) 

A CHOICE(3 '>Copy ') 

A 

A 


Figure 6-15. DDS for a Pull-Down Menu 


On display stations in configurations A and B from Table 6-1 on page 6-2, the pull- 
down menu looks like this: 


File Edit View Help 


O Undo 
O Mark 
© Copy 


RV2W859-1 


Figure 6-16. Pull-Down Menu on a Graphical Display Station with Enhanced Interface 


On display stations in configuration C from Table 6-1 on page 6-2, the pull-down 
menu looks like this: 


File Edit View Help 


RV2W065-0 


Figure 6-17. Pull-Down Menu on a Nongraphical Display Station with Underline Capability 
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On display stations in configurations D and E from Table 6-2 on page 6-3, the pull- 
down menu looks like this: 


File Edit View Help 


RV2W064-0 
Figure 6-18. Pull-Down Menu on a Nongraphical Display Station without Underline Capa- 
bility 


On display stations in configuration F from Table 6-2 on page 6-3, the pull-down 
menu looks like this: 


File Edit View Help 


RV3W073-1 


Figure 6-19. Pull-Down Menu on a Display without Enhanced Interface 


Controlling the Selection Indicators in a Pull-Down Menu 


A selection indicator is an indicator that precedes a choice in a selection field or a 
selection list. It is used to select the choice or to show that a choice has been 
selected. An example of a selection indicator is a radio button. Radio buttons 
appear before choices in single-choice selection fields and single-choice selection 
lists. The default is for selection indicators to appear in selection fields. You can 
suppress the selection indicators in a pull-down menu by specifying the 
*“NOSLTIND parameter on the PULLDOWN keyword. Figure 6-20 is an example of 
the DDS to suppress the selection indicators in a pull-down menu. 


| <2et ein tenet yeys 2 eegatiesa I lsaateyedegsetasesBiyactyacsOs4esPeedal wan 
A R PULLDOWN PULLDOWN (*NOSLTIND) 
A Fl 2Y 0B 1 1SNGCHCFLD 
A 01 CHOICE(1 '>Undo ') 
A CHOICE(2 &MARKTXT) 
A CHOICE(3 '>Copy ') 


Figure 6-20. DDS for Suppressing Selection Indicators in a Pull-Down Menu 


On display stations in configurations A and B from Table 6-1 on page 6-2, the pull- 
down menu looks like this: 
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File Edit View Options Help 


Undo 
Mark 
Copy 


RV2W857-1 


Figure 6-21. Suppressed Selection Indicators on Graphical Display Station 


On display stations in configuration C from Table 6-1 on page 6-2, the pull-down 
menu looks like this: 


File Edit View Options’ Help 


RV2W066-1 


Figure 6-22. Suppressed Selection Indicators on Nongraphical Display Station 


The *NOSLTIND value is ignored for display stations that are not attached to a 
controller that supports an enhanced interface for nonprogrammable work stations. 


Defining Accelerator Keys 
An accelerator key is a function key that starts the application-defined function and 
is displayed next to a pull-down menu choice. 


You can specify accelerators for a single-choice selection field in a pull-down menu 
by doing the following: 


1. Specify the necessary CFnn keys. 
2. Use the CHCACCEL keyword. 


Specify the accelerator text on the CHCACCEL keyword. You can use a P-field to 
specify the text. Note that the CHCACCEL keyword does not define the acceler- 
ator key itself. You must define the CFnn keyword for the key and design your 
application to recognize this key as an accelerator for this choice. You must also 
ensure that the text you specify on CHCACCEL correctly reflects the key you have 
defined. For example, if you want CF08 to be an accelerator key, specify some- 
thing like F8 or CF08 on the CHCACCEL keyword for the appropriate choice. 


The accelerator text appears three spaces after the length of the longest choice 
text in the field. 


Because the accelerator key functions even if the pull-down menu is not displayed, 
you should define the necessary CFnn keys at the file level. If you define them at 
the record level, specify them for every record from which they should be available. 


Single-choice selection fields may be defined in any record. However, an acceler- 


ator can be defined only for a single-choice selection field within a pull-down menu. 
Figure 6-23 on page 6-22 is an example. 
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A R PULLEDIT CF04 CF06 

A PULLDOWN 

A Fl 2Y 0B 1 I1SNGCHCFLD 

A CHECK(ER) 

A 01 CHOICE(1 '>Undo ') 
A CHCACCEL(1 'F4') 

A CHOICE(2 &MARKTXT) 

A CHCACCEL(2 &F6) 

A CHOICE(3 '>Copy ') 
A MARKTXT 20A P 

A F6 2 P 


Figure 6-23. DDS for Accelerator Keys 


On display stations in configurations A and B from Table 6-1 on page 6-2, the pull- 
down menu looks like this: 


File Edit View Options Help 


O Undo F4 
O Mark F6 
© Copy 


RV2W855-1 


Figure 6-24. Accelerators in a Pull-Down Menu 


Defining a Menu-Bar Switch Key 


A menu-bar switch key alternates the cursor between the menu bar and the appli- 
cation display. 


You can define a menu-bar switch key using the MNUBARSW keyword at either 
the file level or the record level. If the cursor is in the application record, pressing 
the menu-bar switch key moves the cursor to the first choice in the menu bar. 
Pressing the key again moves the cursor from the menu bar back to its previous 
location in the application record. If you move the cursor using the cursor keys 
from the application record to the menu bar and then press the menu-bar switch 
key, the cursor returns to its initial position on the application record. This is the 
first input field unless cursor positioning keywords are specified on the application 
record. If a pull-down menu is displayed, pressing the menu-bar switch key 
cancels the pull-down menu and moves the cursor to the application record. 


The system always handles the menu-bar switch key regardless of whether the 
application or the system displayed the menu bar. (For more information, see the 
DDS Reference.) 


For the menu-bar switch key to be active, it must have been active on the last 
record written to the display. The easiest way to ensure that the menu-bar switch 
key will always be active is to specify MNUBARSW at the file level. If you specify 
MNUBARSW at the record level, you must specify it on all records on which it 
should be active. 
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Defining a Cancel Key 
You can define a cancel key for the menu-bar record and pull-down menu records 
using the MNUCNL keyword. You can define them either at the file level or the 
record level. 


A cancel key closes a pull-down menu and moves the cursor to the associated 
choice on the menu bar. This is true even if the cursor is not in the pull-down 
menu. If no pull-down menus are displayed and the cursor is located within the 
menu bar, the key cancels the menu bar and moves the cursor back to the applica- 
tion record. This location is the cursor’s previous location in the application record 
if the menu-bar switch key was used to move the cursor to the menu bar. If the 
cursor had been moved to the menu bar with the cursor keys, this location is the 
initial location of the cursor within the application record. If no pull-down menus are 
displayed and the cursor is located on the application record, the key returns 
control to the application program. In this case, the MNUCNL keyword works just 
as any other key definition keyword, and includes the ability to return a response 
indicator. 


Like the menu-bar switch key, the cancel key is active only if it was active for the 
last record written to the display. The easiest way to ensure that the cancel key 
will always be active is to specify the MNUCNL keyword at the file level. If you use 
the MNUCNL keyword at the record level, you must specify it on all records on 
which it should be active. 


Figure 6-25 shows how to use the MNUBARSW keyword and the MNUCNL 
keyword. The example sets up command attention key 10 as the menu-bar switch 
key and command attention key 12 as the cancel key. (These settings are the 
defaults.) 


eee erty (iene. Serres rarer, An: cree, SN PaRReC: Cen re. Pene Ce reentry Jee 
MNUBARSW(CA10) MNUCNL(CA12) 
R MENUBAR MNUBAR 
MNUFLD 2Y 0B 1 2 
MNUBARCHC(1 PULLFILE + 
'>File ') 
02 MNUBARCHC(2 PULLEDIT + 
&EDITTXT) 
MNUBARCHC(3 PULLVIEW + 
‘>View ') 
04 MNUBARCHC(4 PULLOPT + 
'>Options ') 
MNUBARCHC(5 PULLHELP + 
'>Help ') 
EDITTXT 20A P 
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Figure 6-25. DDS for Menu-Bar Switch Key and Cancel Key 
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Limiting Function When Cursor is Outside a Pull-Down Menu 
If *“NORSTCSR is specified on the PULLDOWN keyword, the user may move the 


cursor out of the active window and use any command function (CF) key. 
“NORSTCSR is the default. 


If *RSTCSR is specified on the PULLDOWN keyword, and the cursor is moved 
outside the pull-down menu, only the Print and Home command function (CF) keys 
are active. If the work station user presses any other command function (CF) key, 
the alarm sounds and the cursor is moved back to its position for the previous write 
operation. 


Selection Lists—Overview 


A selection list is a potentially scrollable list from which the user can select an 
item. There are two types of selection lists: single-choice and multiple-choice. A 
single-choice selection list is a potentially scrollable list from which the user can 
select one item. A multiple-choice selection list is a potentially scrollable list 
from which the user can select one or more items. 


Single-choice selection lists and multiple-choice selection lists contain a group of 
choices displayed in a vertical list. These choices can be scrolled either by using 
the Page Up and Page Down keys or by using a scroll bar. A scroll bar is a part of 
a display that shows a user that more information is available in a particular direc- 
tion and can be moved into view by using a pointing device or the page keys. For 
more information on scroll bars, see “Scroll Bars—Overview” on page 6-30. 


You can select any number of choices from the multiple-choice selection list. You 
can only make one choice from the single-choice selection list. “Selection 
Lists—Overview” shows an example of a single-choice selection list, multiple-choice 
selection list, and scroll bars used with the selection lists. 
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The DDS in Figure 6-28 on page 6-26 produces the following displays: 


On display stations in configurations A and B from Table 6-1 on page 6-2, the 
selection lists look like this: 


Panel Title 


Single selection list : 


Choice text 
Choice text 
Choice text 
Choice text 
Choice text 
More... 


tiple selection list : 


hoice text 
hoice text 
hoice text 
hoice text 
oice text 


AReOaAO = 


More... 


\ 


RV3W077-0 


Figure 6-26. Selection Lists on a Graphical Display Station with Enhanced Interface 


On display stations in configuration F from Table 6-2 on page 6-3, the selection 
lists (vertical format) look like this: 


Panel Title 


Single selection list : 


- Choice text 
/ Choice text 
« Choice text 
- Choice text 
« Choice text 


More... 


Multiple selection list : 


1 Choice text 
£Choice text 
—Choice text 
— Choice text 
—Choice text 


More... 


MS 
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Figure 6-27. Selection Lists on a Nongraphical Display Station with Underline Capability 
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DDS for Selection Lists—Example 
The DDS in Figure 6-28 creates the displays shown in “Selection Lists—Overview” 
on page 6-24. 


SFLMLTCHC (&NUMSEL *RSTCSR) 
SFLPAG(5) SFLSIZ(&SFLSIZ) 
SFLDSP SFLDSPCTL 


A R SFLRCD SFL 

A CTLFLD 1Y OH SFLCHCCTL 

A Fl 11A 0 6 10 

A R SFLCTLRCD SFLCTL(SFLRCD) 

A SFLSNGCHC 

A SFLPAG(5) SFLSIZ(&SFLSIZ) 
A SFLDSP SFLDSPCTL 

A ROLLUP(10) 

A 10 SFLEND(*MORE) 

A F3 5S OH SFLSCROLL 

A F2 4S OH SFLRCDNBR(CURSOR *TOP) 
A SFLSIZ 5S OP 

A 1 30'Panel Title' 

A 4 5'Single selection list:' 
A R SFLRCD2 SFL 

A CTLFLD 1Y OH SFLCHCCTL 

A Fl 11A 0 13 10 

A R SFLCTLRC2 SFLCTL(SFLRCD2) 

A 

A 

A 

A 10 SFLEND(*MORE) 

A ROLLUP(10) 

A F2 4S OH SFLRCDNBR(CURSOR *TOP) 
A F3 5S OH SFLSCROLL 

A SFLSIZ 5S OP 

A NUMSEL 4Y OH 

A 


11 5'Multiple selection list:' 
Figure 6-28. DDS for Selection Lists—Example 


Creating Selection Lists 


Selection lists are created using subfiles. For more information on subfiles, see 
Chapter 4, “Displaying Groups of Records Using Subfiles.” For each selection list 
you must specify a subfile record format and a subfile control record format. Within 
the subfile record format you must specify an output field for the text of the choice. 
You can specify only one output-only field in the record. 


To specify a default choice in a selection list, use either the subfile next-changed 
(SFLNXTCHG) keyword or a control field. To use the SFLNXTCHG keyword, 
specify the keyword on the text field within the subfile record. To use a control 
field, specify a control field in the subfile record and specify the subfile choice 
control (GFLCHCCTL) keyword on the field. The control field can have the fol- 
lowing values: 
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Conirol Value Meaning on Meaning on Input 


Output 
0 Available Not selected 
1 Selected Selected 
2 Unavailable. 


Cannot place 
cursor on choice 
unless help for 
choice is 
available.1,2 


3 Unavailable. 
Placing cursor on 
choice is allowed. 


4 Unavailable. 
Cannot place 
cursor on choice 
even if help for 
choice is 
available.1,2 


1 Applies only to displays attached to a controller that sup- 
ports an enhanced interface for nonprogrammable work 
stations. 


2 lf the choice is the first choice displayed and there are no 
other cursorable choices in the list, the choice will be made 
unavailable and cursorable. Otherwise, an invalid data stream 
error would be issued. 


The application uses the get-next-changed operation to determine which choices 
are selected. The get-next-changed operation returns all of the changed records. 

If the user deselects a default choice, the get-next-changed operation returns the 
deselected choice record because its control value changed. To have the get-next- 
changed operation return only the selected choices, specify the subfile return 
selected choices (SFLRTNSEL) keyword on the subfile control record. The next 
get-next-changed operation will return the selected choice. Then, perform an 
update operation to the default choice to change its control value to 0. 


On display stations in configurations A and B from Table 6-1 on page 6-2, the 
choices are preceded by radio buttons (single-choice) and check boxes (multiple- 
choice). This is true unless *NOSLTIND is specified on the subfile single-choice 
selection list (SFLSNGCHC) and multiple-choice selection list (GFLMLTCHC) 
keywords. The location that you specify for the first field in the subfile record 
format is the location of the input fields (on a character-based nongraphical 
display). On display stations in configurations A and B from Table 6-1 on 

page 6-2, the location of the first field is the location of the first radio button or 
check box. 


Notes: 


1. If you suppress the selection indicators, the location that you specify for the first 
field in the subfile record format is the location of the first character in the first 
choice. 


2. If the selection list is within a pull-down menu, the location you specify is rela- 
tive to the pull-down menu borders. 
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To specify that the cursor remain in the selection list when the cursor movement 
keys are used, use the restrict cursor (*RSTCSR) value on the SFLSNGCHC or 
SFLMLTCHC keywords. If the cursor is on the top record of the subfile and the 
user presses the up cursor key, the subfile rolls up. If the cursor is on the last 
record of the subfile and the user presses the down cursor key, the subfile rolls 
down. 


The SFLSCROLL keyword is used to return the relative record number of the 
record at the top of the current page of records. If the user presses Enter, 
SFLSCROLL returns the relative record number of record that is currently displayed 
at the top of the page. If control is returned to the application because of the 
ROLLUP keyword, SFLSCROLL returns the relative record number of the last 
record in the subfile plus 1. If control is returned to the application because of the 
ROLLDOWN keyword, SFLSCROLL always returns 1. 


To redisplay the subfile with the correct subfile record at the top of the list of 
choices, use the subfile record number (SFLRCDNBR) keyword. Specify 
SFLRCDNBR(*TOP) as a hidden field and use the relative record number returned 
by the SFLSCROLL keyword. Add more records to the subfile and redisplay the 
subfile. 


Controlling the Selection Indicators in a Selection List 


A selection indicator is an indicator that precedes a choice in a selection field or a 
selection list. It is used to select the choice or to show that a choice has been 
selected. An example of a selection indicator is a radio button. Radio buttons 
appear before choices in single-choice selection fields and single-choice selection 
lists. The default is for selection indicators to not appear in selection lists. You can 
have the selection indicators display in a selection list by specifying the *SLTIND 
parameter on the SFLSNGCHC and SFLMLTCHC keywords. 


The *SLTIND value is ignored for display stations that are not attached to a con- 
troller that supports an enhanced interface for nonprogrammable work stations. 
Figure 6-29 on page 6-29 is an example of the DDS to enable the selection indica- 
tors in a selection list. 
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A R SFLRCD SFL 

A CTLFLD 1Y OH SFLCHCCTL 

A Fl 11A 0 6 10 

A R SFLCTLRCD SFLCTL(SFLRCD) 

A SFLSNGCHC (*SLTIND) 

A SFLPAG(5) SFLSIZ(&SFLSIZ) 
A SFLDSP SFLDSPCTL 

A ROLLUP(10) 

A 10 SFLEND(*MORE) 

A F3 5S OH SFLSCROLL 

A F2 4S OH SFLRCDNBR(CURSOR *TOP) 

A SFLSIZ 5S OP 

A 1 30'Panel Title' 

A 4 5'Single selection list:' 
A R SFLRCD2 SFL 

A CTLFLD 1Y OH SFLCHCCTL 

A Fl 11A 0 13 10 

A R SFLCTLRC2 SFLCTL(SFLRCD2) 

A SFLMLTCHC(&NUMSEL *RSTCSR *SLTIND) 
A SFLPAG(5) SFLSIZ(&SFLSIZ) 
A SFLDSP SFLDSPCTL 

A 10 SFLEND(*MORE) 

A ROLLUP(10) 

A F2 4S OH SFLRCDNBR(CURSOR *TOP) 

A F3 5S OH SFLSCROLL 

A SFLSIZ 5S OP 

A NUMSEL 4Y OH 

A 


11 5'Multiple selection list:' 


Figure 6-29. DDS for Enabling Selection Indicators in a Selection List 


On display stations in configurations A and B from Table 6-1 on page 6-2, the 
selection list looks like this: 


Panel Title 


Single selection list : 


© Choice text 
© Choice text 
© Choice text 
© Choice text 
© Choice text 


More... 


Multiple selection list : 


OChoice text 
OChoice text 
OChoice text 
OChoice text 
OChoice text 


More... 


\ 


RV3W0079-0 


Figure 6-30. Selection Indicators on Graphical Display Station 


Chapter 6. Creating a Graphical Look for Displays 6-29 


Scroll Bars—Overview 


A scroll bar is a part of a display that shows a user that more information is avail- 
able in a particular direction and can be moved into view by using a pointing device 
or the page keys. A scroll bar can be defined for any subfile. The examples in this 
section show examples of scroll bars used with a single-choice selection list and a 
multiple-choice selection list. 


The DDS in Figure 6-33 on page 6-33 produces the following displays: 


On display stations in configurations A and B from Table 6-1 on page 6-2, the 
selection lists and scroll bars look like this: 


Panel Title 


Single selection list : 


oice text 
oice text 
oice text 
hoice text 


oice text 


QOON20 


tiple selection list : 


oice text 
oice text 
oice text 
hoice text 


oice text 


QANNRDND & 


NS S/ 


RV3W078-0 


Figure 6-31. Scroll Bar on a Graphical Display Station with Enhanced Interface 
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On display stations in configuration F from Table 6-2 on page 6-3, the selection 
lists (vertical format) look like this: 


Panel Title 


Single selection list : 
. Choice text A 


. Choice text . 
. Choice text * 
. Choice text : 
. Choice text Vv 


Multiple selection list: 


— Choice text 
= Choice text 
— Choice text 
— Choice text 
— Choice text 


More... 


\ 


RV3W080-0 


Figure 6-32. Scroll Bar on a Nongraphical Display Station with Underline Capability 


Creating a Scroll Bar 
To create a scroll bar, use the scroll bar (*“SCRBAR) value on the subfile end 
(SFLEND) keyword. The *SCRBAR value creates a graphical scroll bar on graph- 
ical display stations. It creates a character scroll bar on nongraphical display 
stations. The scroll bar appears to the right of the longest choice in the list. To 
have the scroll bar appear further to the right, add blanks to the text for the 
selection list choices. 


In most cases, the number of subfile records represented by the scroll bar is the 
number of records that have been written to the subfile. The SFLEND keyword 
optioned on indicates that no more records will be written to the subfile. The 
SFLPAG value is not added to the number of records represented by the scroll bar. 
When the bottom of the subfile is reached and the PAGEDOWN keyword is not 
active, the scroll bar box is displayed exactly above the lower scroll bar button. 


The SFLEND keyword optioned off indicates that more records will be written to the 
subfile. The SFLPAG value is added to the number of records represented by the 
scroll bar. Adding the SFLPAG value causes the scroll bar to appear as if more 
subfile records exist after the last subfile record. When the last subfile record is 
reached and the PAGEDOWN keyword is active, the scroll bar box is not displayed 
exactly above the lower scroll bar button. This indicates there are more records to 
display. If the PAGEDOWN keyword is active, control is given back to the applica- 
tion if the user tries to page down or scroll to the unseen records. The application 
can then write more records to the subfile. 


Note: The SFLPAG value is not added to the number of records represented by 
the scroll bar when PAGEDOWN is active and when the number of records 
written is less than the SFLSIZ value. In this case, the number of subfile 
records represented by the scroll bar is the SFLSIZ value. The SFLSIZ 
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value is used to show the total size of the subfile and allows the application 
to fill only the subfile records that the user wants to see. 


If the PAGEDOWN keyword is active, no partial pages are displayed. If the user 
tries to roll to a partial page, control is given back to the application. The subfile 
roll value (SFLROLVAL) may override this. For more information on the 
SFLROLVAL keyword, see the DDS Reference. |f the PAGEDOWN keyword is not 
active, the SFLPAG value minus 1 is added to the number of records represented 
by the scroll bar. Adding the SFLPAG value minus 1 enables a partial page to be 
displayed. 


Note: If a scroll bar is displayed with a horizontal subfile, you may not be able to 
use the top scroll button when the following are true: 


¢ A partial page is reached 
¢ Records are displayed in only the first column of the horizontal subfile 


See Table 6-3 for a summary of how the scroll bar is sized under different condi- 
tions. 


Table 6-3. How a Scroll Bar is Sized 


then the following values are added (yes or no) to 
the number of records represented by the scroll bar 


Relative 
record 
If SFLEND number 
indicator PAGEDOWN and the number of of last 
is ... i records written is ... SFLPAG SFLPAG - 1 record SFLSIZ 
=SFLSIZ No No Yes No 
Active <SFLSIZ No No No Yes 
=SFLSIZ No Yes Yes No 
On Not active <SFLSIZ No Yes Yes No 
=SFLSIZ Yes No Yes No 
Active <SFLSIZ No No No Yes 
=SFLSIZ Yes Yes Yes No 
Off Not active <SFLSIZ Yes Yes Yes No 
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DDS for Scroll Bars—Example 


The DDS in Figure 6-33 creates the displays shown in “Scroll Bars—Overview” on 


page 6-30. 


R SFLRCD 

CTLFLD 

Fl 1 
SFLCTLRCD 


Po) 


10 
F3 
F2 
SFLSIZ 


Po) 


SFLRCD2 

CTLFLD 

Fl 1 
SFLCTLRC2 


wm 


10 


NUMSEL 


rFrrrrrrrrrrrrrrrrrrrrrrrrrrsy 


Figure 6-33. DDS for Scroll Bars—Example 


Scroll Bar Operation 


SFLCHCCTL 


SFLCTL(SFLRCD) 

SFLSNGCHC 

SFLPAG(5) SFLSIZ(&SFLSIZ) 
SFLDSP SFLDSPCTL 
ROLLUP(10) 
SFLEND(*SCRBAR) 

SFLSCROLL 
SFLRCDNBR(CURSOR TOP) 


1 30'Panel Title' 
4 5'Single selection list:' 


SFL 
SFLCHCCTL 


13 10 


SFLCTL(SFLRCD2) 

SFLMLTCHC (&NUMSEL *RSTCSR) 
SFLPAG(5) SFLSIZ(&SFLSIZ) 
SFLDSP SFLDSPCTL 
SFLEND(*SCRBAR *MORE) 
ROLLUP(10) 
SFLRCDNBR(CURSOR TOP) 
SFLSCROLL 


5'Multiple selection list:' 


See Table 6-4 for a summary of how the scroll bar operates. 


Table 6-4. Scroll Bar Operation 


If the user ... 


then ... 


Clicks once on the top scroll button 


The subfile is scrolled one record toward 
the bottom of the subfile 


Clicks once on the bottom scroll button 


The subfile is scrolled one record toward 
the top of the subfile 


Clicks once on the shaft above the scroll 
box or presses the Page Down key 


The subfile is scrolled one page toward the 
bottom of the subfile 


Clicks once on the shaft below the scroll 
box or presses the Page Up key 


The subfile is scrolled one page toward the 
top of the subfile 


Drags the scroll box with the selection 
button and releases the selection button 
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The subfile page is scrolled to correspond 
to the position indicated by the scroll box 
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Push Buttons—Overview 


A push button is a button, labeled with text, graphics, or both that represents an 
action that starts when a user selects the push button. 


The DDS in Figure 6-38 on page 6-35 produces the following displays: 


On display stations in configurations A and B from Table 6-1 on page 6-2, the 
push buttons look like this: 


Fi=he lip F3=Exit FA=Prompt 
< 


RV3W070-0 


Figure 6-34. Push Buttons on a Graphical Display Station with Enhanced Interface 


On display stations in configuration C from Table 6-1 on page 6-2, the push 
buttons look like this: 


< Fl=Help > <F3=Exit > <F4=Prompt> 
X 


RV3W071-0 


Figure 6-35. Push Buttons on a Nongraphical Display Station with Underline Capability 


On display stations in configurations D and E from Table 6-1 on page 6-2, the 
push buttons look like this: 


< Fl=Help > <F3=Exit > <F4=Prompt> 
XX 


RV3W072-0 


Figure 6-36. Push Buttons on a Nongraphical Display Station without Underline Capability 


On display stations in configuration F from Table 6-1 on page 6-2, the push 
buttons look like this: 


< Fl=Help > <F3=Exit > <F4=Prompt> 
Ne 


RV3W074-0 


Figure 6-37. Push Buttons on a Display Station without Enhanced Interface 
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DDS for Push Buttons—Example 


The DDS in Figure 6-38 creates the displays shown in “Push Buttons—Overview” 


on page 6-34. 
[emtheawole sakes es vluetete twa deseet coved watet coe Sango taas Osetia Tee 
A R RECORD 
A 
A PSHFLD1 2Y QB 23 4PSHBTNFLD(*RSTCSR (*NUMCOL 3)) 
A PSHBTNCHC(1 'F1l=>Help' HELP) 
A PSHBTNCHC(2 &F3 CFO3) 
A CHCCTL(2 &CTL) 
A 02 PSHBTNCHC(3 'F4=>Prompt' CF04) 
A CHCAVAIL((*COLOR RED) ) 
A F3 15A P 
A CTL 1Y OH 


Figure 6-38. DDS for Push Buttons—Example 


Creating Push Buttons 
A push button field is defined with the push button field (PSHBTNFLD) keyword. 
Each push button field must contain one or more push button choice 
(PSHBTNCHC) keywords. 


Push buttons can be displayed vertically or horizontally (the default). The 
“NUMROW value on the PSHBTNFLD keyword specifies the number of rows to 
use when displaying the push buttons vertically. The *NUMCOL value on the 
PSHBTNFLD keyword specifies the number of columns to use when displaying the 
push buttons horizontally. When no parameters are specified on the PSHBTNFLD 
keyword, the push buttons are displayed in as many columns that fit on one line. 


Use the choice control (CHCCTL) keyword to control the availability of the indi- 
vidual push buttons. Use the choice available (CHCAVAIL) and choice unavailable 
(CHCUNAVAIL) keywords to control the color or attribute of the individual push 
buttons. 


Specify a key for each push button. In the following example, the CF04 key is 
returned when the F4=Prompt push button is selected: 

PSHBTNCHC(3 'F4=>Prompt' CF04) 
If you do not specify a key, Enter is returned when the push button is selected. 


The key defined in the push button choice is automatically enabled for the record 
that contains the push button field. 


The field that contains the push button contains the number of the push button 
choice that is selected. If the user presses the key associated with a push button 
(instead of selecting the push button itself), the number of the push button is not 
returned. Zero is returned if no choice is made. 


Help can be specified for each push button. 
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Controlling the Availability of Choices 


You can control the availability of the choices in a selection field and push button 
choices using the CHCCTL keyword. For information on controlling the availability 
of choices in selection lists, see “Creating Selection Lists” on page 6-26. Specify 
the name of a hidden field on the CHCCTL keyword. Your program can set a 
value in this field to specify whether the choice is available, unavailable, or selected 
(multiple-choice selection fields only). Figure 6-39 describes the control values and 
their meanings. 


Control Value Sets Choice to 


0 Available (or not selected) 
1 Selected 
2 Unavailable. 
Cannot place cursor on choice unless help for choice is available. 
3 Unavailable. 
Placing cursor on choice is allowed. 
4 Unavailable. 


Cannot place cursor on choice even if help for choice is available. 
Figure 6-39. Control Values for the CHCCTL Keyword 


Note: The cursor restrictions in Figure 6-39 apply only to displays attached to a 
controller that supports an enhanced interface for nonprogrammable work 
stations. 


Value 1 is ignored for single-choice selection fields, because default selection is 
done by setting the selection in the single-choice selection field itself. It is also 
ignored for push buttons. Value 1 is used for multiple-choice selection fields to let 
more than one choice default to the selected choice. 


You can also specify a message to be displayed if the user selects an unavailable 
choice. If you do not specify a message, the system displays a default message. 
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Figure 6-40 is an example of the DDS to control the availability of choices showing 
a single-choice selection field in an ordinary record: 


| nosy te eavtheede2eey et ecsdeveet covebes Veto ceBsoiit cB geet elie 
A R RECORD 
A 2 2'Flavor... ' 
A Fl 2Y 0B 2 16SNGCHCFLD 
A CHOICE(1 '>Chocolate ') 
A CHCCTL(1 &CTLCHOC MSG1112 QUSER/A) 
A 01 CHOICE(2 '>Strawberry ') 
A CHCCTL(2 &CTLSTRA &MSG &LIB/&MSGF) 
A CHOICE(3 '>Vanilla ') 
A CHCCTL(3 &CTLVANT) 
A CHOICE(5 '>Peach ') 
A CTLCHOC 1Y OH 
A CTLSTRA 1Y OH 
A CTLVANI 1Y OH 
A MSG 7A P 
A LIB 10A P 
A MSGF 10A P 


Figure 6-40. DDS to Control the Availability of Choices 


On display stations in configuration C from Table 6-1 on page 6-2 and configura- 
tions D, E, and F from Table 6-2 on page 6-3, the single-choice selection field 
looks like this: 


. Chocolate 
. Strawberry 
. Vanilla 

. Peach 


Flavor... 


awnrF 


Figure 6-41. Single-Choice Selection Field with an Unavailable Choice. Assume that at 
run time, CTLCHOC and CTLSTRA are set to 0 (available) and CTLVANI is set to 2 (una- 
vailable). The choice text, Vanilla, appears gray to indicate it is unavailable. 


Auto-Selection in Single-Choice Selection Fields 


The auto-selection function allows a user to select a choice in a single-choice 
selection field by placing the cursor on the choice and pressing Enter. It is not 
necessary to select the choice by 1) typing the choice number, 2) placing the 
cursor on the choice and pressing the spacebar, or 3) placing the pointer on the 
choice and pressing the left mouse button. This is the default for single-choice 
selection fields in a pull-down menu. The default for single-choice selection fields 
that are not in a pull-down menu is manual selection. The *“AUTOSLT parameter 
on the SNGCHCFLD keyword indicates that the choice should be automatically 
selected when Enter is pressed. The *“NOAUTOSLT parameter indicates that the 
choice must be manually selected. The *AUTOSLTENH parameter indicates that 
auto-selection is only in effect for displays attached to a controller that supports an 
enhanced interface for nonprogrammable workstations. 
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Auto-Enter in Single-Choice Selection Fields 


The auto-enter function allows a selected choice to be returned to the program 
when the choice is selected. It is not necessary to press Enter to return the choice. 
The *“AUTOENT parameter indicates that the Enter key will be returned as soon as 
the choice is selected. The choice is automatically returned on all display stations 
except where a double-digit selection number is required for any of the choices. 
The *NOAUTOENT parameter indicates that the choice will not be returned until the 
user presses Enter after selecting the choice. “NOAUTOENT is the default. The 
“AUTOENTNN parameter indicates that the choice will be returned as soon as the 
choice is selected only if numeric selection of the choice is not required. 


Defining Mnemonics 
You can define mnemonics for these items: 


e Menu-bar choices 

¢ Selection field choices (single and multiple) 
¢ Selection list choices (single and multiple) 
e Push buttons 


Define mnemonics using a greater-than (>) character. To identify a mnemonic, 
place the > character just before the character that you want to be the mnemonic. 
The > character is not counted as part of the text length. If you want to use the > 
character as a character in the text rather than as a pointer to the mnemonic, you 
must use two > characters consecutively. If you specify the > character as the last 
character in the text, the > character appears as part of the text and no mnemonic 
appears. Figure 6-42 is an example. 


Keyword Specification Text Appears as 
MNUBARCHC(1 PULLFILE '>File') File 
MNUBARCHC(2 PULLFIN 'Fsinish') Finish 

CHOICE(1 ‘Save >As...') Save As... 
CHOICE(2 'X >= 1') X=1 

CHOICE(3 'X >>>= 1') X >= 1 


You cannot specify the > character as a mnemonic. 
Figure 6-42. Examples of Valid DDS for Mnemonics 


The mnemonic cannot be a blank. Only one mnemonic may be specified in the 
choice text. If more than one mnemonic is specified, only the first mnemonic is 
selectable. Figure 6-43 is an example of incorrect coding. 


Keyword Specification Error 

MNUBARCHC(1 PULLFILE '>File') Same mnemonic specified for 
MNUBARCHC(2 PULLFIN '>finish’) more than one choice. 
CHOICE(1 'S>ave >As...') Two mnemonic characters 
CHOICE(4 'X >>>= >1') specified. 


Figure 6-43. Examples of DDS Not Valid for Mnemonics 


You can select a mnemonic by typing either the uppercase or lowercase mnemonic 
character. This is true for all languages. The system uses the monocase rules for 
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the appropriate language to identify the mnemonic you typed. Double-byte charac- 
ters cannot be mnemonics. 


Because the system does not support both mnemonic and numeric selection for a 
field, mnemonics work only when choices are not displayed using numbers. 


To determine which configurations support mnemonics, see Table 6-1 on 
page 6-2. 


Defining Choice Colors and Attributes 


Normally, the system uses the Common User Access* (CUA) default colors and 
display attributes when displaying menu-bar choices, selection-field choices, 
selection list choices, and push button choices. If you do not want to use these 
defaults, you can define the colors and attributes to be used for most choices using 
the CHCAVAIL, CHCUNAVAIL, and CHCSLT keywords. Table 6-5 shows which 
keywords can be used with each graphical item. 


Table 6-5. Keywords Used to Define Colors and Display Attributes 


DDS Keyword 
Graphical Item CHCAVAIL CHCUNAVAIL CHCSLT 
Menu-Bar Choice X X 
Selection Fields X X X 
Push Buttons X X 
Single Choice X X X 
Selection List 
Multiple Choice Xx xX xX 


Selection List 


The selection cursor on display stations attached to a controller that supports an 
enhanced interface for nonprogrammable work stations uses the reverse image 
form of the colors and attributes you specify for each of the choice states. For 
example, if you specify pink (normal display) for the available choices, the selection 
cursor is reverse image pink when it is located on an available choice. If you 
specify pink reverse image for the available choices, the selection cursor is pink 
(normal display). Likewise, if you do not specify CHCAVAIL, CHCUNAVAIL, or 
CHCSLT and use the CUA default colors and attributes, the selection cursor is the 
reverse image of those colors and attributes. 


You can use only the CHCAVAIL keyword and the CHCSLT keyword for menu bars 
because menu-bar choices are either available or selected. For selection fields, 
use only the CHCAVAIL keyword and the CHCUNAVAIL keyword when you are 
using selection characters (for example, numbers or radio buttons). The CHCSLT 
keyword is ignored in these cases. However, you can use CHCSLT for selection 
fields in a pull-down menu on graphical display stations or character-based graph- 
ical display stations when you have specified that the pull-down menu should not 
contain selection indicators (PULLDOWN(*NOSLTIND) specified). 


You can use only the CHCAVAIL keyword and the CHCUNAVAIL keyword for push 
buttons because push button choices are either available or unavailable. 
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The display-attribute (‘DSPATR) parameter specifies the way in which the sepa- 
rator characters display. The parameter is expressed in this form: 


(*DSPATR valuel <value2 <value3...>>) 


The valid values for the display attributes are: 


Value Meaning 

BL Blink 

cS Column separator 
HI High intensity 

ND Nondisplay 

RI Reverse image 
UL Underline 


The default display attribute for unavailable choices in a selection field on 
monochrome display stations is normal (or low) intensity. Also, the first character 
of an unavailable choice on a monochrome display station is overwritten with an 
asterisk (*). 


Display attributes CS, HI, and BL can cause fields on 5292, 3179, and 3197 Model 
C1 and C2 display stations to appear as color fields. Display attributes HI, Rl, and 
UL cause a separator line not to be displayed. For more information, see the 
CHCAVAIL keyword, the CHCUNAVAIL keyword, and the CHCSLT keyword in 
DDS Reference. 


In Figure 6-44, the choices in the menu bar are displayed in white on color display 
stations and in high intensity on monochrome display stations. When a menu-bar 
choice is selected, it is displayed in green on color display stations and reverts to 
normal (not high intensity) display on monochrome display stations. 


| costtace leave ehacwnlaverteese Sever tes ood opvetes cobuanstie vs Ovaee tease vee 
R MENUBAR MNUBAR 
MNUFLD 2Y OB 1 2 
MNUBARCHC(1 PULLFILE + 
'>File ty) 
02 MNUBARCHC(2 PULLEDIT + 
&EDITTXT) 
MNUBARCHC(3 PULLVIEW + 
‘>View ') 
04 MNUBARCHC(4 PULLOPT + 
'>Options ') 
MNUBARCHC(5 PULLHELP + 
'>Help ') 
MNUBARSEP((*COLOR WHT) ) 
CHCAVAIL((*COLOR WHT) (*DSPATR HI)) 
CHCSLT((*COLOR GRN) ) 


rFrrrrrrrrrrrrrrsS 


EDITTXT 20A P 


Figure 6-44. DDS Using CHCAVAIL and CHCSLT for Menu-Bar Choices 


In Figure 6-45 on page 6-41, the available selection-field choices are displayed in 
pink on color display stations and in high intensity on monochrome display stations. 
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The unavailable selection-field choices are displayed in turquoise on color display 
stations. On monochrome display stations, the unavailable choices are displayed 
with normal (or low) intensity, and the first character in the choices is overwritten 
with an asterisk (*). 


| cdo Peview Leave Pvevelicest ccysdessgtyxsdise shee eebie ees eeOr ees Fea Teen 


rFrrrrrrrrrrrrrsty 


01 


Fl 


CTLCHOC 
CTLSTRA 
CTLVANI 
MSG 

LIB 
MSGF 


2Y OB 


1SNGCHCFLD 

CHOICE(1 '>Chocolate ') 

CHOICE(2 '>Strawberry ') 

CHOICE(3 '>Vanilla ') 

CHCCTL(1 &CTLCHOC MSG1112 QUSER/A) 
CHCCTL(2 &CTLSTRA &MSG &LIB/&MSGF) 
CHCCTL(3 &CTLVANI) 

CHCAVAIL((*COLOR PNK) (*DSPATR HI)) 
CHCUNAVAIL((*COLOR TRQ)) 


Figure 6-45. DDS Using CHCAVAIL and CHCUNAVAIL for Selection Fields 


In Figure 6-46, the selection-field choice that is selected is displayed in yellow. If 
CHECK(ER) (automatic-enter) is specified on this field, control is returned imme- 


diately after selecting the choice. 


a eee: ee, Oe Poe, amen ae, ee Si ee ee ees eee ee eee 


rFPrrrrrrrrrrrrsts 


01 


R PULLDOWN 


Fl 


CTLUNDO 
CTLMARK 
CTLCOPY 


2Y OB 


1Y OH 
1Y OH 
1Y OH 


PULLDOWN (*NOSLTIND) 
1SNGCHCFLD 

CHOICE(1 '>Undo ') 
CHOICE(2 '>Mark ’) 
CHOICE(3 '>Copy ') 

CHCCTL(1 &CTLUNDO MSG1112 QUSER/A) 
CHCCTL(2 &CTLMARK &MSG &LIB/&MSGF) 
CHCCTL(3 &CTLCOPY) 

CHCAVAIL((*COLOR PNK) (*DSPATR HI)) 
CHCUNAVAIL( (*COLOR TRQ)) 
CHCSLT((*COLOR YLW)) 


Figure 6-46. DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Selection Fields 


In Figure 6-47, the DDS source for a Single Choice Selection list is shown (the 
example does not show all the keywords necessary for a correct subfile definition). 
Available choices within the list will be displayed in yellow. Unavailable choices will 
be displayed in red. The selected choice will be displayed in green. 
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R SFLREC SFL 
CTLFLD 1Y OH SFLCHCCTL 
R SFLCTLRCD SFLCTL(SFLREC) 
SFLSNGCHC 


CHCAVAIL((*COLOR YLW)) 
CHCUNAVAIL((*COLOR RED) ) 
CHCSLT((*COLOR GRN) ) 


rFPrrrrrrrrsyE 


Figure 6-47. DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Single Choice 
Selection List Choices 


In Figure 6-48, the DDS source for a Multiple Choice Selection list is shown (the 
example does not show all the keywords necessary for a correct subfile definition). 
Available choices within the list will be displayed in yellow. Unavailable choices will 
be displayed in red. Any selected choices will be displayed in green. 


ees er ee ee ee Pere ener ee rene eee: meee. Were, One eee, Sey Se 
A R SFLREC SFL 
A CTLFLD 1Y OH SFLCHCCTL 
A R SFLCTLRCD SFLCTL(SFLREC) 
A SFLMLTCHC 
A 
A 
A P 
A CHCAVAIL((*COLOR YLW)) 
A CHCUNAVAIL((*COLOR RED) ) 
A CHCSLT((*COLOR GRN) ) 


Figure 6-48. DDS Using CHCAVAIL, CHCUNAVAIL, and CHCSLT for Multiple Choice 
Selection List Choices 


Continued-Entry Fields—Overview 


A continued-eniry field is a set of associated entry fields. Continued-entry fields 
are supported on displays attached to any controller. Controllers that support an 
enhanced interface for nonprogrammable work stations treat continued-entry fields 
as single-entry fields while data is being entered and edited in the fields. 


Note: Controllers that do not support an enhanced interface for nonprogrammable 
work stations treat continued-entry fields as separate input fields. Insert 
and delete characters one segment at a time. When you reach the end of a 
segment, the cursor does not move automatically to the next segment. 


Figure 6-49 on page 6-43 illustrates the use of continued-entry fields to create a 


rectangular text entry field. Consider using this format to avoid using a single input 
field that wraps across multiple lines. 
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Note: The empty space at the end of the last line is still part of the continued- 
entry field. You cannot define another field in this space. 


Enter Text... 


Figure 6-49. Continued-Entry Fields in Rectangular Arrangement 


A continued-entry field allows a multiple-row entry field to be defined inside of a 
window or display. 


The DDS for the field looks like this: 


eee eee eee oy een, ee Fae ee: eee een ee ees eee, ene eee 
A Fl 90A B 3  4ACNTFLD(30) 


The CNTFLD keyword tells the system that this is a continued-entry field and its 
parameter tells the system how wide the field should be. The system breaks the 
field into columns and uses as many lines as it needs to reach the specified width. 


Specifying Word Wrap on Continued-Entry Fields 
To specify the word wrap function for a continued-entry field, use the word wrap 
(WRDWRAP) keyword. This keyword can be used at the file, record, or field level. 


Note: WRDWRAP cannot be used on DBCS continued-entry fields. 


For more information about the WRDWRAP keyword, see “Specifying Word Wrap 
for Fields” on page 2-20. 


DBCS Considerations with Continued-Entry Fields 
DDS supports these DBCS data types: 


J Only (only bracketed DBCS characters allowed) 

E Either (either only SBCS or only bracketed DBCS characters allowed) 
O Open (either SBCS or bracketed DBCS characters allowed - mixed) 
G ~~ Graphic/Pure (only nonbracketed DBCS characters allowed) 


These data types will have the following restrictions: 


J The width of each continued-entry field segment must be an even number of 
at least 4 bytes. 


E The width of each continued-entry field segment must be an even number of 
at least 4 bytes. 


O The width of each continued-entry field segment must be at least 4 bytes 
wide. 


G___ The width of each continued-entry field segment must be an even number of 
at least 4 bytes. 


The length of the DBCS continued-entry field must account for the SO/SI character 
pairs that bracket the DBCS data on each segment of the continued-entry field. 
The following total field lengths are required to ensure the field data fits into DBCS 
continued-entry fields: 
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J or E (with DBCS data) 
Data Length + (Number of segments - 1) * 


2 
O Data Length + (Number of segments - 1) * 3 


G or E (with SBCS data) 
Data Length 


Note: The (Number of segments - 1) * 3 portion of the calculation in the second 
equation allows for the SO/SI sets that must bracket the DBCS data on the 
segments of the continued-entry field after the first segment. Additional 
consideration is made for the possibility that a NULL must be placed at the 
end of a segment wherever a DBCS character would be split. 


How DBCS Data is Returned for Continued-Entry Fields 


If the field is a DBCS-only or DBCS-either (with DBCS data) field, the following data 
is not returned to the application: 


e¢ The extra SO characters at the start of the middle and last segments 


e The extra SI characters at the end of the first and middle segments 


If the field is a DBCS-open field, the following are removed before the field is 
returned to the application: 


e All single byte subfields at the end of a segment which consist only of one null 
or are empty. This is to remove any SO/SI pairs that most likely have been 
automatically inserted as a result of double byte data falling on a segment 
boundary. Removing the extra SI/SO characters occurs for all hardware 
regardless of whether the controller supports an enhanced interface for nonpro- 
grammable work stations. 


e Single byte nulls that end a segment if the following is true: 
— The number of nulls is three or less 
— The previous character is not an SI character or null 
— The next segment begins with an SO character 


This is to remove any nulls that most likely have automatically been inserted as 
a result of double byte data falling on a segment boundary. 


Keyboard Functions with Continued-Entry Fields 


The system processes local keyboard functions specified within the continued-entry 
fields on a display station attached to a controller that supports an enhanced inter- 
face for nonprogrammable work stations by the following definitions: 


Character data 

In replace mode, there is no unique character data processing. When character 
data is entered in the last character position of the first or one of the middle fields 
in the set, the cursor moves to the first character position of the next field in the 
set. When character data is entered in the last character position of the last field in 
the continued fields, forward field-exit processing is performed (see “Forward Field- 
Exit Processing” on page 6-49). 


In insert mode and cursor direction matches field direction, the following actions 
occur when a character data key is pressed: 
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The null in the last character position of the last field in the continued-entry 
fields is deleted. If there is no null in the last position of this field, operator 
error 0012 is posted. 

All field data within the continued-entry fields at (and logically following) the 
current cursor location are shifted one position. Each data character in the last 
character position of the current and remaining fields (except the last) in the set 
is shifted to the first character position of the following field. 

The data character entered is written at the cursor location. 

The cursor advances to the next cursor position. 

For DBCS-only, DBCS-either (with DBCS data), and DBCS-pure fields, the two 
nulls in the last two character positions (before the SI for DBCS-only or 
DBCS-either fields) of the last segment of the continued field are deleted. If 
there are not nulls in the last two positions of that segment, operator error 0012 
is posted. Otherwise, all field data (not including the SO or SI characters) 
within the set of field segments at and logically following the current cursor 
location is shifted two positions in the cursor direction. Each double byte char- 
acter in the last two character positions of the current and remaining segments 
(except the last) is moved to the first two character positions of the following 
segment. The DBCS character entered is written at the cursor location, and 
the cursor advances to the next double byte cursor position. 

For DBCS-open fields the data in the continued field segments, at and to the 
right of the cursor, is copied into one continuous buffer. The inserted character 
is placed at the start of the buffer. All single byte nulls are removed from the 
buffer, and the data is shifted toward the beginning of the buffer. All adjacent 
SI/SO character pairs (that is, empty single byte subfields) are also removed 
from the buffer. The data is again shifted toward the beginning of the buffer. 
The data is then placed back into the continued field one character at a time, 
according to the algorithm for writing data into a DBCS-open continued field. 
The remaining character positions are replaced with nulls. The cursor also 
advances to the next character position. If all the data in the buffer cannot fit 
into the continued field, operator error 0012 is posted, and the field data and 
cursor position are not changed. 


In insert mode and cursor direction does not match field direction, the insert takes 
place within a subfield. The insert is the same as if the field and cursor direction 
matched, but the insert is performed within the subfield. The extent of a subfield is 
defined as follows: 


When the cursor direction is right-to-left, the subfield extends from the cursor to 
the first null logically following the cursor. If there is no such null, the subfield 
includes all positions logically following the cursor. 


When the cursor direction is left-to-right, the subfield extends from the cursor to 
the first null logically following the cursor. If there is no such null, the subfield 
includes all positions logically following the cursor. 


Field Mark 
Processed the same as character data. 
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Automatic Shape Determination (ASD) Processing 
For Arabic, ASD occurs if the cursor direction is right-to-left. 


Delete 
If the delete key is pressed within a continued-entry field and the cursor direction 
matches the field direction, the following actions occur: 


¢ All field data within the continued-entry fields logically following the current 
cursor location is shifted toward the cursor one position. Each data character 
in the first character position of the remaining fields in the set is shifted to the 
last character position of the preceding field. 

¢ A null is written in the last character position in the continued-entry fields. 

¢ For DBCS-only, DBCS-either (with DBCS data), and DBCS-pure continued 
fields, all field data (not including the SO and SI characters) within the set of 
field segments logically following the current cursor location is shifted toward 
the cursor two positions. Each DBCS character in the first double byte char- 
acter position of the remaining segments is moved to the last double byte char- 
acter position of the preceding segment. A double byte null is written in the 
last double byte character position of the last segment. 

¢ For DBCS-open fields, the data in the set of field segments, at and to the right 
of the cursor, is copied into one continuous buffer. The deleted character or 
subfield is removed from the start of the buffer. In addition, all single byte nulls 
are removed from the buffer, and the data is shifted toward the beginning of the 
buffer. All adjacent SI/SO character pairs (that is, empty single byte subfields) 
are also removed from the buffer. The data is again shifted toward the begin- 
ning of the buffer. The remaining data, then, is placed back into the continued 
field one character at a time, according to the algorithm for writing data into a 
DBCS-open continued field. The remaining character positions are replaced 
with nulls. 


If the delete key is pressed within a continued field when the cursor direction and 
field direction do not match, the delete is performed within a subfield. The defi- 
nition for subfields is the same as for the insert key. 


Erase EOF 

All field positions at (and logically following) the current cursor location within the 
continued-entry fields are nulled. In DBCS-only, DBCS-either (with DBCS data), 
and DBCS-pure fields, the SO and SI characters are not nulled out. In DBCS-open 
fields, an SI character may additionally be written at the current cursor location if 
the erase began in a double byte subfield. 


Erase Input 

All field positions of all changed fields are nulled. This includes all continued-entry 
field segments if any continued-entry field segment has been changed. In 
DBCS-only, DBCS-either (with DBCS data), and DBCS-pure fields, the SO and SI 
characters are not nulled out. 


Reverse 

The cursor direction is reversed. If the preceding keystroke was not a cursor 
movement key, the cursor is repositioned to the new first character position of the 
current segment. 
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Close 

The close key operates on a single continued field segment. All embedded nulls 
are removed. The cursor direction is set to the field direction. The remaining char- 
acters are shifted to begin at the first character position of the continued field 
segment. The remainder of the segment is padded with nulls and the cursor is 
placed logically following the last non-null character. 


Field Exit 
Pressing the Field Exit key within a continued-entry field causes the following 
actions to occur: 


¢ All field data within the continued-entry fields at (and logically following) the 
current cursor location are nulled. In DBCS-only, DBCS-either (with DBCS 
data), and DBCS-pure fields, the SO and SI characters are not nulled out. In 
DBCS-open fields, an SI character may additionally be written at the current 
cursor location if the nulling began in a double byte subfield. 

¢ Forward field-exit processing is performed (see “Forward Field-Exit Processing” 
on page 6-49). 


Field Plus 
Processed the same as Field Exit. 


Field Minus 
Not allowed. Operator error 0016 is posted. 


Dup 
Pressing the Dup key within a continued-entry field causes the following actions to 
occur: 


¢ All field data within the continued-entry fields at (and logically following) the 
current cursor location are set to the Dup character (1C). In DBCS-only, 
DBCS-either (with DBCS data), and DBCS-pure fields, the SO and SI charac- 
ters are not replaced with the Dup character. In DBCS-open fields, the cursor 
must be on the very first character (whether it is a single byte or double byte 
character) when the Dup key is pressed. Every character of every segment is 
replaced with the Dup character ('1C’') including all SO and SI characters. If the 
cursor is not on the first character, operator error 0019 is posted. 

¢ Forward field-exit processing is performed (see “Forward Field-Exit Processing” 
on page 6-49). 


Kanji 
The Kanji key causes the following actions to occur when pressed within a 
DBCS-either continued field: 


e If the cursor is not at the first field position (when in single byte mode) of the 
first segment, or at the second field position (when in double byte mode) of the 
first segment, operator error 0062 is posted. 

¢ Otherwise, if the field is currently in double byte mode, it is placed into single 
byte mode by replacing every character position of every segment with nulls. 
The cursor is also placed at the first field position of the first segment. 

e Otherwise, if the field is currently in single byte mode, it is placed into double 
byte mode by replacing every character position of every segment with nulls, 
and writing SO and SI characters at the start and end of each field segment 
respectively. The cursor is also placed in the first segment immediately fol- 
lowing the shift out character. 
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In DBCS-open continued fields, the Kanji key inserts either a SO/SI character pair, 
or an SI/SO character pair as is currently done for non-continued open fields. For 
continued fields, this insert is performed using the same algorithm that characters 
are inserted into an DBCS-open continued field. However, when a SI/SO pair is 
inserted, the empty single byte subfield that is created is not immediately removed. 
The cursor is also placed under the second shift character and the keyboard goes 
into insert mode. 


Character Backspace 

Pressing the Character Backspace key in the first position (or first DBCS character 
in any DBCS-pure, DBCS-only, or DBCS-either field) of the first segment, moves 
the cursor to the last position of the previous field. (The previous field could be a 
continued-entry field. The cursor moves to the last position of the last segment 
which could be further down on the display.) If the resulting cursor position is in a 
DBCS-open, DBCS-only, or DBCS-either field, any SI character at the last position 
is skipped. Pressing the Character Backspace key in the first position in a segment 
(or first DBCS character in DBCS-pure, DBCS-only, or DBCS-either fields in double 
byte mode) other than the first segment, moves the cursor to the last position of the 
previous segment. If that resulting position is on a DBCS-only or DBCS-either field 
SI character, the SI character is skipped. In addition, within DBCS-open fields, 
single byte subfields at the end of a non-last segment are skipped by character 
backspace if they consist only of 1 null character. This is to skip nulls that most 
likely have been automatically inserted when splitting DBCS data on segment 
boundaries. 


Character Advance 

Pressing the Character Advance key in the last position (or last double byte char- 
acter in DBCS-pure, DBCS-only, or DBCS-either fields in double byte mode) of the 
last segment, moves the cursor to the first position of the next field. Pressing the 
Character Advance key in the last position (or last double byte character in 
DBCS-pure, DBCS-only, or DBCS-either fields in double byte mode) of a segment 
other than the last segment, moves the cursor to the first position of the next 
segment. If the resulting position is on a DBCS-only or DBCS-either field SO char- 
acter, the SO character is skipped. In DBCS-open fields, single byte subfields at 
the end of a segment are skipped if they consist of only one null. This is to skip 
nulls that most likely have been automatically inserted when splitting DBCS data on 
segment boundaries. 


New Line 

Pressing the New Line key generally moves the cursor to the next position on the 
display that allows a cursor. If the cursor is in a continued-entry field and an addi- 
tional continued-entry field segment is on the next row or a subsequent row, the 
cursor moves to the first position of that segment. If the continued-entry field is 
also a highlighted field with an invisible text cursor, then pressing the New Line key 
exits the continued-entry field. If the resulting position is in a new DBCS-open, 
DBCS-only, or DBCS-either field segment of the same field, any SO character at 
the resulting cursor location is skipped. When the cursor moves into a continued- 
entry field because the New Line key was pressed, the cursor is always positioned 
in the first position of the first segment. Pressing the New Line key never moves 
the cursor into a middle or last continued-entry field segment. 
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Field Advance 


Field Advance performs forward field-exit processing (see “Forward Field-Exit 
Processing’). 


Field Backspace 

When pressed while the cursor is not in the first position (or first DBCS character in 
a DBCS-pure, DBCS-only, or DBCS-either field) of the first segment, the cursor 
moves to the first position (or first DBCS character in a DBCS-pure, DBCS-only, or 
DBCS-either field) of the first segment. Otherwise, Field Backspace performs back- 
ward field-exit processing (see “Backward Field-Exit Processing”). 


Forward Field-Exit Processing 


The system does not validate field data when the cursor exits continued-entry fields 
because mandatory fill and self-check functions are not supported. 


If the continued-entry fields are specified as automatic-enter or forward-edge 
trigger, the system performs automatic-enter or forward-edge trigger processing for 
the last position of the last segment. 


If cursor progression is specified on the first continued-entry field segment, the 
cursor moves to the cursor-progression target field when it exits any of the 
continued-entry field segments. 


If cursor progression is not specified on the first continued-entry field segment, and 
the cursor exits the continued-entry field in the forward direction, the cursor skips 
any subsequent segments of the continued-entry field and moves to the next non- 
protected field. The next nonprotected field is determined by exiting the first con- 
tinued field segment, independent of which segment contained the cursor. If the 
resulting position is in a DBCS-open, DBCS-only or DBCS-either field, any SO 
character at the first position is skipped. The cursor is placed at the second posi- 
tion. 


Note: If a continued-entry field is also defined as a highlighted field, the system 
restores the leading-field attribute of each segment when the cursor exits 
the field. 


Backward Field-Exit Processing 


When exiting the field backward, the cursor skips any previous segments of the 
continued-entry field and moves to the previous nonprotected field. Cursor 
progression may cause the cursor to move to a different field. The previous non- 
protected field is determined by exiting the first continued field segment, inde- 
pendent of which segment contained the cursor. If the resulting position is in a 
DBCS-open, DBCS-only or DBCS-either field, any SO character at the first position 
is skipped. The cursor is placed at the second position. 


Note: DBCS support within continued-entry fields are available for displays 
attached to any controller. However, the keyboard functions are only available for 
displays connected to a controller that supports an enhanced interface for nonpro- 
grammable work stations. 
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How the Menu Bar Interacts with the Application 


The MNUBARDSP keyword is used to display a menu bar. The MNUBARDSP 
keyword can be used on an application record (the record that defines the applica- 
tion display) or on a menu-bar record. Option indicators can be used on the 
MNUBARDSP keyword to control when the menu bar is displayed. If 
MNUBARDSP is used on the application record, several optioned MNUBARDSP 
keywords can be specified so that the application can display different menu bars 
for the same record. If more than one MNUBARDSP keyword is in effect, the 
system uses the first one. 


Defining the MNUBARDSP Keyword on the Application Record 


When the MNUBARDSP keyword is used on the record that defines the application 
display, the system handles all menu-bar operations for the application. The 
system returns the number of the menu-bar choice selected in a hidden field that is 
specified on the MNUBARDSP keyword and defined in the application record. If no 
menu-bar choice is selected, 0 is returned in the hidden field. 


lebety veces veHeeso2eesatuessdecdePecocdycastecs Se caste ce Oc cee Fes vy Tees 
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02 MNUBARCHC(2 PULLEDIT + 
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Figure 6-50. DDS Using MNUBARDSP on the Application Record 


The DDS in Figure 6-50 causes the following to happen: 


1. The application writes any pull-down menu records or menu-bar records that 
have output to be supplied by the application. 


2. The application does a write-read operation to the record with the 
MNUBARDSP keyword. 


3. The system displays the menu bar identified by the MNUBARDSP keyword and 
handles all interaction between the menu bar and the pull-down menu. 
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4. If the user selects a menu-bar choice and enters input in the pull-down menu, 
the system returns the number of the menu-bar choice selected in the choice- 
hidden field specified on MNUBARDSP. 


The system displays the menu-bar record first and then performs the write-read 
operation to the application record. The active function keys and command keys 
are those defined on the application record and not those defined on the menu-bar 
record. If you want to use the MNUCNL keyword or the MNUBARSW keyword, 
define them at the file level or on the application record. 


Ordinarily, writing a record to the display without the OVERLAY keyword causes 
the entire display to be erased before the record is displayed. The system displays 
the menu-bar record followed by the application record as if they were logically one 
record. The system automatically prevents the application record from erasing the 
menu-bar record. In Figure 6-50 on page 6-50, when the system writes the appli- 
cation record, it clears the entire display except for the menu-bar record. The 
menu-bar record is always processed as though it contains the OVERLAY keyword 
regardless of any other specifications. For example, if the CLRL keyword is speci- 
fied on the menu-bar record, it is not used when the menu-bar record is processed. 
The OVERLAY keyword and the CLRL keyword are processed normally for the 
application record; however, the menu-bar record is not cleared. 


Defining the MNUBARDSP Keyword on the Menu-Bar Record 


If you use the MNUBARDSP keyword on the record containing the menu bar, the 
application controls when the menu bar is displayed. The system continues to 
handle any pull-down menu interaction that takes place, and returns the number of 
the menu-bar choice selected in the menu-bar field itself. If no menu-bar choice 
was selected, 0 is returned in the menu-bar field. The application must both write 
the menu-bar record to display the menu bar and read the menu-bar record to 
determine what choice, if any, was selected. 
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Figure 6-51. DDS Using MNUBARDSP on the Menu-Bar Record 


Following is one scenario using the DDS in Figure 6-51. 


1. The application writes the menu-bar record, with the MNUBARDSP keyword 
active, to display the menu bar. 


2. The application does a write-read operation to the application record. 


3. The system handles any interaction between the menu bar and the pull-down 
menu. 


4. On input, the application receives the application record. 
5. The application reads the menu-bar record to determine which menu-bar 
choice, if any, was selected. 


The only active command keys and function keys are those defined on the applica- 
tion record and not those defined on the menu-bar record. If you want to use the 
MNUCNL keyword or the MNUBARSW keyword, define them at the file level or on 
the application record. 
Following is another scenario using the DDS in Figure 6-51. 

1. The application writes the application record. 


2. The application performs a write-read operation to the menu-bar record, with 
the MNUBARDSP keyword active, to display the menu bar. 


3. The system handles any interaction between the menu bar and the pull-down 
menu. 


4. On input, the application receives the menu-bar record and determines which 
menu-bar choice, if any, was selected. 
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5. The application can also read the application record to receive any input 
entered on the display. 


The only command keys and function keys that are valid are those defined on the 
menu-bar record. If you want to use the MNUCNL keyword or the MNUBARSW 
keyword, define them at the file level or on the menu-bar record. 


Receiving Input from the Pull-Down Menus 


If a pull-down menu record contains output data, it must be written before writing 
the menu-bar record. For example, option indicators may be set or output fields 
may be filled in. These pull-down menu records are not displayed when written; 
the system processes and saves the record output until the menu bar is displayed. 


A menu-bar record may also be written without being displayed. If the system 
attempts to write a pull-down menu record or a menu-bar record (without the 
MNUBARDSP keyword optioned on) while the corresponding menu bar is dis- 
played, an error occurs and the record is not written. 


When a valid attention identifier (AID) key (other than the cancel key and the 
menu-bar switch key) is pressed when a pull-down menu is displayed, control is 
returned to the application and input may be received from the pull-down menu. 
The valid AID keys that return input are the Enter key and any CFxx keys that are 
defined on the pull-down menu record. (A CAxx key returns control to the applica- 
tion, but does not return input.) Keys that are defined for the background display 
are not valid unless they are also defined on the pull-down menu record. There- 
fore, define the background keys and the pull-down menu keys once at the file 
level. 


Once a valid AID key (one that returns input) is pressed for a pull-down menu, the 
application receives input for the record being read (either the application record or 
the menu-bar record). By looking at the menu-bar choice number that is returned 
in this record, the application can determine which pull-down menu record has 
input. The application then must read that pull-down menu record. No I/O opera- 
tion is done to the display; the input from the pull-down menu is returned to the 
application and the pull-down menu remains displayed. 


Receiving Input from Pull-Down Menus Using the Pull-Down 
Input Parameter 

When one or more of the pull-down menu records contain only one single-choice 
selection field, you can use the pull-down input (PULLINPUT) parameter on the 
MNUBARDSP keyword. This lets you receive the single-selection field choice 
along with the menu-bar choice, instead of reading the pull-down menu record to 
receive the single-selection field choice. 


Figure 6-52 on page 6-54 illustrates the use of the PULLINPUT parameter on the 
MNUBARDSP keyword. 
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Figure 6-52. DDS for Pull-Down Input (PULLINPUT) Parameter 


When the PULLINPUT parameter is specified on the MNUBARDSP keyword, one 
of the following values will be returned to the application: 


Note: The value is returned in the hidden field (PULLINPUT in Figure 6-52) you 
have defined in the record with the MNUBARDSP keyword. 


PULLINPUT Contents Meaning 


0 No selection made. 
n Choice n in the pull-down menu was selected. 
-1 Pull-down menu record contains something other than 


one single-choice selection field. You must read the 
pull-down menu record to receive its contents. 


Table 6-6 on page 6-55 shows the values that are returned in the MNUCHOICE 
field and the PULLINPUT field using the DDS in Figure 6-52. 
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Table 6-6. Values Returned in MNUCHOICE and PULLINPUT 


Value Returned in Appropriate Field 


Menu-Bar Choice Selected MNUCHOICE PULLINPUT 
File 1 -1 
Edit (no selection made in pull-down menu) 2 0 
Edit (Copy choice in pull-down menu selected) 2 1 
View 3 -1 


Removing a Pull-Down Menu after Receiving Input 
After the application receives input from a pull-down menu, it may remove the pull- 
down menu under certain conditions. For example, the application removes the 
pull-down menu when the application writes or reads (1) a non-window record (in 
the same display file) or (2) a window record (in the same display file) that contains 
the RMVWDW keyword. The pull-down menu remains on the display if the applica- 
tion writes or reads a window record (without RMVWDW). This allows the applica- 
tion, UIM help, or application help to write a help window to the display without 
removing the pull-down menu. 


To remove a pull-down menu and present another non-window application display, 
the application writes the appropriate application record, and the pull-down menu is 
removed. 


To remove the pull-down menu and keep the current application display (perhaps 
updated), the application performs another write-read (or read) operation to the 
current (or changed) application record. 


To remove the pull-down menu and display a window, the application writes a 
window with the RMVWDW keyword specified. 


To remove the pull-down menu and call another program, the application writes to 
a dummy record and then calls the other program. 


To leave the pull-down menu on the display and present a window (perhaps a help 
window), the application writes the window record (without RMVWDW). 


A pull-down menu remains on the display while UIM help is displayed in a window. 
A pull-down menu also remains on the display while application help is displayed if 
the application help record is a window and does not have the RMVWDW keyword 
specified. 


Updating a Pull-Down Menu before Displaying 
You can enable your application to update a pull-down menu using the return-field 
parameter on the MNUBARCHC keyword. The pull-down menu is updated after a 
menu-bar choice is selected and before the pull-down menu is displayed. The 
return-field parameter is a hidden field that returns the number of the choice 
selected for the application to (1) determine that control was returned before the 
pull-down menu was displayed rather than because input was entered in the pull- 
down menu, and (2) determine which pull-down menu record to update and write. 


Chapter 6. Creating a Graphical Look for Displays 6-55 


A R MENUBAR MNUBAR 

A MNUFLD 2Y OB 1 2 

A MNUBARCHC(1 PULLFILE + 

A '>File ' &RTNFLD) 
A MNUBARCHC (4 PULLOPT + 

A '>Options ‘+ 
A &RTNFLD) 

A RTNFLD 2Y OH 

A R PULLFILE 

A PULLDOWN 

A Fl 2Y 0B 1  1SNGCHCFLD 

A R PULLOPT 

A PULLDOWN 


A Fl 2Y OB 1  1SNGCHCFLD 


Figure 6-53. DDS for Return-Field Parameter 


For the DDS in Figure 6-53, if the user selects menu-bar choice 1 or 4, control is 
returned to the application with the choice number set in the RTNFLD field. The 
menu-bar field or the choice field in the application record contains 0, indicating no 
pull-down menu input was received. The application must read the menu-bar 
record to get the contents of the RTNFLD field. The application then updates the 
pull-down menu record for that choice and writes it. The application must read the 
menu-bar record or the application record to request the display. After control has 
been returned for updating the pull-down menu, the next record written must be the 
pull-down menu specified on the MNUBARCHC keyword. In this example, if choice 
1 was selected, record PULLFILE must be written; if choice 4 was selected, record 
PULLOPT must be written. The system then displays the pull-down menu for the 
choice and resumes control of the menu bar and pull-down menu interaction. A 
read operation to a pull-down menu is not allowed until input has been received for 
the pull-down menu. A write-read operation is never allowed. 


Defining Application Help 


You can define application help for menu-bar choices, selection-field choices, 
named fields, constant fields, menu bars, and pull-down menus. 


Defining Choice-Level Help 


You can define help for menu-bar choices, single-choice selection fields, and 
multiple-choice selection fields using the HLPARA keyword. Figure 6-54 on 
page 6-57 is an example of the DDS coding for menu-bar choice help. 
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Figure 6-54. DDS for Menu-Bar Choice Help 


Figure 6-55 is an example of the DDS coding for single-selection field choice help. 
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HLPARA(*FLD F1 1) 
HLPRCD(UNDOHLP LIB/FILE) 
HLPARA(*FLD F1 2) 
HLPRCD(MARKHLP LIB/FILE) 
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CHECK(ER) 
CHOICE(1 '>Undo ') 
CHOICE(2 '>Mark ') 


CHOICE(3 '>Copy 


Figure 6-55. DDS for Single-Selection Field Choice Help 


Use the «FLD special value on the HLPARA keyword to indicate that the help area 
is for a field. Following *FLD, specify the name of the field for which you are 
defining help. Following the name of the field, specify the number of the choice for 


which you are defining help. 
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The help area that you specify for a choice is the area that the choice text occupies 
(plus the attribute byte positions on either side). If compression occurs, the help 
area moves with the choice. When a choice is optioned off, the help specification 
for that choice is also optioned off because the help area for that choice does not 
exist. 


As with any help specification, the text for choice-level help can be defined using 
DDS records (HLPRCD keyword), OfficeVision* documents (HLPDOC keyword), or 
UIM panel groups (HLPPNLGRP). 


Help specifications must define help areas within the area encompassed by the 
menu-bar record or the pull-down record. 


If you use UIM help, item-specific help for a menu-bar choice includes the help 
modules for the menu-bar choice and its pull-down menu. If you use DDS or 
OfficeVision document help, item-specific help for the menu-bar choice is the help 
for the menu-bar choice. The help area for the menu-bar choice includes the text 
for the choice plus one space on each side of the text. The middle space between 
the choices is part of the extended help area. 


Item-specific help for menu bars is displayed when the cursor is located in one of 
the following areas: 


¢ A menu-bar choice (if there is help for that choice). 


e¢ Anywhere within an active pull-down record that does not include an active help 
area. When the cursor is on the pull-down menu border, item-specific help is 
displayed for the menu-bar choice item. 


Item-specific help for a pull-down menu choice is displayed when the cursor is in an 
active help area in the pull-down menu. The help area for a pull-down menu 
choice starts on the first digit of the number and ends at the border of the selection 
field. Help for pull-down menus and menu bars are part of the extended help for 
the display. When the pull-down menu is displayed, all help areas are active 
except the ones that are overlapped by the pull-down menu. Help for overlapped 
areas can be viewed only in extended help. If a base display help area is partially 
overlapped by a pull-down menu, the part of the help area that is not overlapped is 
still active. 


There are two help lists; one for the base display and one for the menu bar and its 
pull-down menus. The help list for the menu bar is created when the menu bar is 
displayed. The help list is destroyed when the menu bar is removed from the 
display. For an example of a help list for a menu bar, see Figure 6-56 on 

page 6-59. The help list is updated when the menu bar or pull-down menu is 
written again. When the cursor is in a menu bar or pull-down menu, the menu-bar 
help list is searched for item-specific help. The menu-bar help list is considered 
above the base-display help list. When extended help is displayed, help for menu 
bars and pull-down menus is presented immediately after general help. Base 
display help is presented after menu-bar help and pull-down menu help. If DDS 
help is used and the user initially selects pull-down menu help, the user then can 
page up to see menu-bar help and page down to see base-display help. 
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Figure 6-56. A Help List for a Menu Bar 


Defining Help for a Field 
Help can be defined for a field or constant using the HLPARA keyword. For a 
named field, specify the help area using the *FLD special value and the name of 
the field. For a constant field, specify the help area using the *CNST special value 
and an identifier for the constant field. The identifier you specify on the HLPARA 
keyword should be the same as the value specified on the HLPID keyword for the 
constant field. 
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A HELP 
A R RECORD 
A H HLPARA(*FLD FIELD) 
A HLPRCD(FIELDHLP LIB/FILE) 
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Figure 6-57. Help for a Named Field 
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Figure 6-58. Help for a Constant Field 
When the display file is created, the actual help area coordinates are determined by 


the DDS compiler. These coordinates are shown in the expanded source section 
of the DDS listing (unless the field is a choice field). 
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If the field or constant field location or length is changed and the file is re-created, 
the help area for the field is updated to reflect the new location or length. 


Key Interaction for Menu Bars and Pull-Down Menus 


Figure 6-59 shows an example of a display you might create with a menu bar and 
a pull-down menu. Capital letters A, B, C, D, and E indicate possible cursor 
locations. 
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Figure 6-59. Cursor Locations 


Table 6-7 on page 6-61 describes the actions that are performed when certain 
keys are pressed at the cursor locations. 
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Table 6-7. Actions Performed at Different Cursor Locations 


Action Performed When Appropriate Key Is Pressed 


Cursor 
Location Help Cancel Menu-Bar Switch Enter 

A Help for File Pull-down menu is Pull-down menu is File pull-down menu is 
menu-bar choice is removed. Cursor removed. Cursor displayed; Edit pull- 
displayed. (Includes moves to Edit returns to display down menu is removed. 
help for the pull-down menu-bar choice. work area. 
menu.) 

/B | Extended help is dis- Pull-down menu is Pull-down menu is Cursor not on menu bar 
played. removed. Cursor removed. Cursor choice message is dis- 

moves to Edit returns to display played. Cursor does 
menu-bar choice. work area. not move. 

Help for Undo choice Pull-down menu is Pull-down menu is If user made a 
is displayed. removed. Cursor removed. Cursor selection, control 

moves to Edit returns to display returns to application. If 

menu-bar choice. work area. not, cursor moves to 
input field and message 
to make a selection is 
sent. 

D | Help for Edit Pull-down menu is Pull-down menu is If user made a 
menu-bar choice is removed. Cursor removed. Cursor selection, control 
displayed. (Includes moves to Edit returns to display returns to application. If 
help for the pull-down menu-bar choice. work area. not, cursor moves to 
menu.) input field and message 

to make a selection is 
sent. 

E | Help for function keys Pull-down menu is Pull-down menu is If user made a 


is displayed. 


removed. Cursor 
moves to Edit 
menu-bar choice. 


removed. Cursor 
returns to display 
work area. 


selection, control 
returns to application. If 
not, sound beep and 
cursor moves to input 
field. 


Cursor Movement 


You can move the cursor on the application displays that you create using the Tab 
key or the Cursor keys. 


Pressing the Tab Key 


Pressing the tab key moves the cursor from field to field on the display, progressing 


from left to right and top to bottom. 


On display stations in configuration F from Table 6-2 on page 6-3, the following is 


true: 


e The Menu-bar choices are individual fields. 
e The single-choice selection field is one field. 


e¢ The multiple-choice selection fields are individual fields. 


Pressing the Tab key for one of these displays when no pull-down menu is dis- 
played moves the cursor from choice to choice in the menu bar. Then, the cursor 
moves from input field to input field on the rest of the display. When a pull-down 
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menu is displayed on one of these displays, pressing the Tab key does the fol- 
lowing: 


1. Moves the cursor from choice to choice in the menu bar. 
2. Skips over the choice selected. 
3. Moves the cursor from input field to input field within the pull-down menu. 


4. Moves the cursor back to the first choice in the menu bar (the pull-down menu 
for that choice is not automatically displayed). 


While the pull-down menu is displayed, you cannot enter data in the input fields on 
the base display nor can you tab to the input fields. 


On display stations in configurations A, B, and C from Table 6-1 on page 6-2, and 
configurations D and E from Table 6-2 on page 6-3, the menu bar is a single field. 
If no pull-down menu is displayed, pressing the Tab key moves the cursor from 
choice to choice within the menu bar. The cursor performs a wraparound. When a 
menu-bar choice is selected, the cursor is placed in the first input field within the 
pull-down menu. Pressing the Tab key moves the cursor from input field to input 
field within the pull-down menu and then moves the cursor to the next menu-bar 
choice. While the pull-down menu is displayed, you cannot enter data in the input 
fields on the base display nor can you tab to the input fields on the base display. 


Pressing the Cursor Keys 
On display stations in configuration F from Table 6-2 on page 6-3, pressing a 
cursor key moves the cursor one position in the appropriate direction. 


On display stations in configurations A, B, and C from Table 6-1 on page 6-2, and 
configurations D and E from Table 6-2 on page 6-3, the cursor moves differently 
depending on the type of field it is in. 


e In the menu bar, pressing the cursor-right or cursor-left keys moves the cursor 
from choice to choice. The cursor does not perform a wraparound. 

e In the base display, pressing any cursor key moves the cursor one position in 
the appropriate direction. 

e When the cursor is positioned on a selection field, see: 


— “Cursor Movement in a Vertical Selection Field” on page 6-15. 


— “Cursor Movement in a Horizontal Selection Field” on page 6-16. 


Programming Examples 


Following are examples of the DDS required to display a menu bar and a pull-down 
menu with a description of how the DDS coding works. 


Using the MNUBARDSP Keyword on the Application Record 
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A HELP ALTHELP CFO3 
A MNUBARSW(CA10) MNUCNL(CA12) 
A CFO4(04) CF06(06) 
A R MENUBAR MNUBAR 
A H HLPARA(*FLD MNUFLD 1) 
A HLPRCD(FILEHLP HLPLIB/HLPFILE) 
A H HLPARA(*FLD MNUFLD 2) 
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MNUBARCHC(1 PULLFILE + 

'>File : 
MNUBARCHC(2 PULLEDIT + 

&EDITTXT) 
MNUBARCHC(3 PULLVIEW + 

‘>View ') 
MNUBARCHC (4 PULLOPT + 

'>Options ' &RTNFLD) 
MNUBARCHC(5 PULLHELP + 

'>Help ') 
MNUBARSEP( (*COLOR WHT) ) 
CHCAVAIL((*COLOR YLW) (*DSPATR HI)) 
CHCSLT((*COLOR GRN) ) 
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HLPRCD(MARKHLP HLPLIB/HLPFILE) 
HLPARA(*FLD F1 3) 
HLPRCD(COPYHLP HLPLIB/HLPFILE) 
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CHECK(ER) 

CHOICE(1 '>Undo ') 
CHOICE(2 &MARKTXT) 
CHOICE(3 '>Copy ') 


CHCCTL(1 &CTLUNDO MSG1112 QUSER/A) 
CHCCTL(2 &CTLMARK &MSG &LIB/&MSGF) 
CHCCTL(3 &CTLCOPY) 

CHCACCEL(1 'F4') 

CHCACCEL(2 'F6') 

CHCAVAIL((*COLOR WHT) ) 
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PULLDOWN 
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R APPSCR MNUBARDSP(MENUBAR &MNUCHOICE + 


A 
A &PULLINPUT) 
A FIELD1 10A B10 12 
A FIELD2 5S 0B 14 12 
A 24 1'Fl=Help F3=Exit + 
A F10=Actions  F12=Cancel : 
A MNUCHOICE 2Y OH 
A PULLINPUT 2S OH 
Description 


In the example using the MNUBARDSP keyword on the application record, the 
application does a write-read operation to the APPSCR record. This causes the 
MENUBAR record and the APPSCR record to be displayed. Because the field 
EDITTXT in the MENUBAR record contains the text >Edit, Edit is displayed as the 
text for the second menu-bar choice. 


Pressing the F10 key provides quick access to the menu bar (which is always 
active). Pressing F10 moves the cursor to the first choice in the menu bar. 
Pressing F10 again (or F12) moves the cursor back to where it was on the applica- 
tion display. On display stations in configuration F from Table 6-2 on page 6-3, 
pressing the Tab key moves the cursor from choice to choice in the menu bar. The 
cursor skips over any menu-bar choice that is selected. It then moves from input 
field to input field on the entire display. On display stations in configurations A, B, 
and C from Table 6-1 on page 6-2, and configurations D and E from Table 6-2 on 
page 6-3, when the cursor is located within a menu bar, the cursor movement keys 
or the Tab key moves the cursor from choice to choice within the menu bar. 


If the user selects the Edit action, the system displays the pull-down menu record 
(PULLEDIT). CHECK(ER) specifies automatic-enter. When the user types a value 
in F1, control is returned to the application without the user having to press the 
Enter key. If the user presses F4 or F6, control is also returned to the application. 


Because the application performed a write-read operation to the APPSCR record, 
the APPSCR record is returned to the application. Field MNUCHOICE contains a 2 
to identify that menu-bar choice 2 was selected. The PULLINPUT field contains the 
single-selection field choice (the contents of F1) of the PULLEDIT record. 


If the user selects the Options action, control is returned to the application, with 4 
set in field RTNFLD and 0 set in field MNUCHOICE. The application determines 
from the 0 in field MNUCHOICE that control has been returned for pull-down menu 
update. The application reads record MENUBAR to obtain the choice number set 
in field RTNFLD. The application updates the record PULLOPT and then writes 
record PULLOPT. The system then displays PULLOPT as the pull-down menu for 
the options choice. The system resumes control of the menu bar interaction when 
the application performs a read operation to the APPSCR record. 


On display stations in configurations A and B from Table 6-1 on page 6-2, the 
menu bar separator and the pull-down menus display as solid lines. 


On display stations in configuration C from Table 6-1 on page 6-2, and configura- 
tions D, E, and F from Table 6-2 on page 6-3), the menu-bar separator is made up 
of dashes. The side and bottom borders of the pull-down menu are made up of 
colons and periods, respectively. 
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On display stations in configuration C from Table 6-1 on page 6-2, each menu-bar 
choice has a mnemonic. On display stations in configurations A and B from 

Table 6-1 on page 6-2, each single-selection field choice in the PULLEDIT pull- 
down menu has a mnemonic. This is true unless ENHDSP(*NO) is specified on 
the CRTDSPF command or CHGDSPF command). In this example, the mnemonic 
has been set up to be the first character in each of the choices. 


Using the MNUBARDSP Keyword on the Menu-Bar Record 
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HELP ALTHELP CFQ3(03) 
MNUBARSW(CA10) MNUCNL(CA12 12) 
CF04(04) CFO6(06) 

MNUBAR 

MNUBARDSP 

HLPARA(*FLD MNUFLD 1) 
HLPRCD(FILEHLP HLPLIB/HLPFILE) 
HLPARA(*FLD MNUFLD 2) 
HLPRCD(EDITHLP HLPLIB/HLPFILE) 
HLPARA(*FLD MNUFLD 3) 
HLPRCD(VIEWHLP HLPLIB/HLPFILE) 
HLPARA(*FLD MNUFLD 4) 
HLPRCD(OPTHLP HLPLIB/HLPFILE) 
HLPARA(*FLD MNUFLD 5) 
HLPRCD(HELPHLP HLPLIB/HLPFILE) 


2 


MNUBARCHC(1 PULLFILE + 
'>File ') 

MNUBARCHC(2 PULLEDIT + 
&EDITTXT) 

MNUBARCHC (3 PULLVIEW + 
‘>View ') 

MNUBARCHC(4 PULLOPT + 
'>Options ' &RTNFLD) 

MNUBARCHC(5 PULLHELP + 
'>Help ') 

MNUBARSEP((*COLOR WHT) + 

(*CHAR '-')) 


PULLDOWN 

HLPARA(*FLD F1 1) 
HLPRCD(UNDOHLP HLPLIB/HLPFILE) 
HLPARA(*FLD F1 2) 
HLPRCD(MARKHLP HLPLIB/HLPFILE) 
HLPARA(*FLD F1 3) 
HLPRCD(COPYHLP HLPLIB/HLPFILE) 
1SNGCHCFLD 


CHOICE(1 '>Undo ') 
CHOICE(2 &MARKTXT) 
CHOICE(3 '>Copy ') 


CHCCTL(1 &CTLUNDO MSG1112 QUSER/A) 
CHCCTL(2 &CTLMARK &MSG &LIB/&MSGF) 
CHCCTL(3 &CTLCOPY) 

CHCACCEL(1 'F4') 

CHCACCEL(2 'F6') 
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A CTLUNDO 1Y OH 

A CTLMARK 1Y OH 

A CTLCOPY 1Y OH 

A MSG 7A P 

A LIB 10A P 

A MSGF 10A P 

A 

A R PULLOPT 

A PULLDOWN 

A H HLPARA(*FLD F1 1) 

A Fl ZY OB 1  I1SNGCHCFLD 

A 

A R APPSCR 

A FIELD1 10A B10 12 

A FIELD2 5S 0B 14 12 

A 24 1'Fl=Help F3=Exit + 

A Fl1Q@=Actions  F12=Cancel : 
Description 


In the example using the MNUBARDSP keyword on the menu-bar record, the appli- 
cation writes the MENUBAR record to display the menu bar. The application then 
performs a write-read operation to the APPSCR record to display the application 
display. 


As in the previous example, F10 provides quick access to the menu bar (which is 
always active). Pressing F10 moves the cursor to the first choice in the menu bar. 
Pressing F10 again (or F12) moves the cursor back to where it was on the applica- 
tion display. 


On display stations in configuration F from Table 6-2 on page 6-3, pressing the 
Tab key moves the cursor from choice to choice in the menu bar and from input 
field to input field on the entire display. The cursor skips over any menu-bar choice 
that is selected. 


When the cursor is located within a menu bar on display stations in configurations 
A, B, and C from Table 6-1 on page 6-2, and configurations D and E from 

Table 6-2 on page 6-3, the cursor movement keys or the Tab key moves the 
cursor from choice to choice within the menu bar. 


If the user selects the Edit action, the system displays the pull-down menu record 
(PULLEDIT). Because CHECK(ER) is not specified on field F1, the user enters a 
value by typing the choice number and pressing the Enter key, or by pressing F4 or 
F6. When a value is entered or an accelerator key is pressed, control is returned 
to the application. Because the application was doing a write-read operation to the 
APPSCR record, the APPSCR record is returned to the application. The applica- 
tion must then read the MENUBAR record to determine the choice selected (2 is 
returned in field MNUFLD). Because the input-field parameter was not specified on 
the MNUBARDSP keyword, the application reads record PULLEDIT to receive the 
pull-down menu input. 
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How the Displays Look 
On display stations in configurations A and B from Table 6-1 on page 6-2, the 
display looks like this: 


File Edit View Options Help 


O Undo F4 
O Mark F6 
O Copy 


RV2W855-1 


On display stations in configuration C from Table 6-1 on page 6-2, the display 
looks like this: 


File Edit View Options Help 


1. Undo F4 
2. Mark F6 
3. Copy 


RV2W067-0 


On display stations in configurations D and E from Table 6-2 on page 6-3, the 
display looks like this: 


File Edit View Options Help 


— 1, Undo F4 
2. Mark F6 
3. Copy 


RV2W068-1 


On display stations in configuration F in Table 6-2 on page 6-3, the display looks 
like this: 


File Edit View Options Help 


RV3W075-0 


Chapter 6. Creating a Graphical Look for Displays 6-67 


Simple Hotspots 


Controllers that support an enhanced interface for nonprogrammable work stations 
provide simple hotspots. A hotspot is an area of a display that, when clicked on, 
performs a function. You must have a display station with a mouse. Hotspots are 
available on configurations A and B from Table 6-1 on page 6-2. On InfoWindow 
Il display stations, the hotspot must be selected with the left mouse button. 


The following hotspots are provided by controllers that support an enhanced inter- 
face for nonprogrammable work stations: 


Command key emulation 
Page Up and Page Down key emulation 
Enter key emulation 


The user can perform the Enter function on InfoWindow II display stations by 
double-clicking the left mouse button. 


Command Key Emulation 
When the user clicks on a command key, the pointer device cursor must be 
between the first and last characters (inclusive) of the command key. When the 
user selects the command key, the keyboard locks and the command key is pro- 
cessed. The function performed is defined by DDS. The system performs the 
function as if the actual command key had been pressed. This includes setting 
response indicators. 


When the user clicks on a command key, the system scans the command key text 
to the left until it finds one of the following: 


An attribute 

Two blanks 

Two nulls 

A blank and a null 
Column one of the row 


After finding the beginning of the command key text string, the system scans the 
text to the right until it finds a match with one of the following: 
Fx= x can be 1 to 9. 


Fyx= y can be 0, 1, or 2. If yis 0, x canbe 1 to 9. If y is 1, x can be 0 to 9. 
If y is 2, x can be 0 to 4. 


PFx= x can be 1 to 9. 


PFyx= y canbe 0, 1,or2. If yis 0, x canbe 1 to 9. If y is 1, x can be 0 to 9. 
If y is 2, x can be 0 to 4. 


PFx x can be 1 to 9. 


PFyx y can be 0, 1, or 2. If yis 0, x canbe 1 to 9. If y is 1, x can be 0 to 9. 
If y is 2, x can be 0 to 4. 


After the system finds a match, it performs the command key function. 
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Page Up and Page Down Key Emulation 
The user can click on the plus (+) and minus (-) characters to page down (roll up) 
and page up (roll down), respectively. When the user clicks on the + or — charac- 
ters, the keyboard locks and a Roll Up AID key and Roll Down AID key is gener- 
ated. The function performed is defined by DDS. The system performs the 
function as if the actual key had been pressed. 


One way to implement this function is to do the following: 


1. Specify “MORE on the Subfile End (SFLEND) keyword. 


This causes the display file to use the text defined on the CPX6AB2 and 
CPX6AB1 messages. The default text for these messages is More ... and 
Bottom, respectively. 


2. Change the text for the CPX6AB2 message to More: +/-. 
3. Change the text for the CPX6AB1 message to Bottom: -. 


Programmable Mouse Buttons—Overview 


The programmable mouse buttons function allows attention indicators (AlDs) to be 
associated with various pointer device events. AID codes are normally associated 
with various command keys on the keyboard. These keys are used to communi- 
cate action requests from the user to the system or application. Some command 
keys that generate AIDs are Enter, Help, Rollup, Rolldown, and the 24 command 
attention or function keys. Single event AlDs and two event AIDs can be pro- 
grammed. Up to 18 pairs of pointer device events and associated AIDs may be 
defined. These events consist of 3 buttons with 3 events each (up, down, and 
double click) in two keyboard states (shifted and unshifted). 


A single event AID definition would also associate an AID code with a single pointer 
device event whereas the two event AID definition would also associate an AID 
with two consecutive pointer device events. 


Use the programmable mouse button (MOUBTN) keyword to associate a command 
key or Event-ID with one or two pointer device events. This keyword can be speci- 
fied at the file or record level. 


Notes: 


1. This function is available only for displays attached to a controller that supports 
an enhanced interface for nonprogrammable work stations. 


2. The only pointer device supported is a mouse or a device that emulates a 
mouse. 


Pointer Device Events 
With a three button mouse, there are 18 pointer device events possible: 3 buttons 
with 3 events each (up, down, double click) in two keyboard states (shifted and 
unshifted). The pointer device events are: 


e Left button pressed 

e Left button released 

e Left button double click 
e Right button pressed 
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e Right button released 

e Right button double click 

e Middle button pressed 

e Middle button released 

e Middle button double click 
Shifted left button pressed 
Shifted left button released 
Shifted left button double click 
Shifted right button pressed 

¢ Shifted right button released 

e Shifted right button double click 
e Shifted middle button pressed 
e Shifted middle button released 
e Shifted middle button double click 


Notes: 


1. The Shift key or Shift Lock key must be held down for a shifted pointer device 
event. Caps Lock state and Shift Lock state are not considered shifted. 
Releasing the Shift key does not reset Caps Lock state or Shift Lock state if 
used for a shifted pointer device event. 


2. The nonprogrammable work station (NWS) has a setup option to switch the 
functions of the left and right buttons within the NWS. The system has no 
knowledge of this. This provides the concept of left- and right-handed mice. 
For this document, all references to the mouse buttons assumes a right-handed 
mouse where the left and right buttons follow the usual definitions for left and 
right. 


AID Codes to be Returned 


Programmable 


The AID associated with a pointer device event may be any currently supported 
AID or a host-defined AID value between X'70' and X'7F'. The following AlDs 
are supported: 


X'31' - X'3C' CA/CF01-CA/CF12 (Cmd 1 - 12) 
X'70' - X'7F' E00-E15 (EVENTS) 
X'B1' - X'BC' CA/CF13-CA/CF24 (Cmd 13 - 24) 


X'BD' CLEAR (Clear) 

X'F1' Enter or Record Advance 
X'F3' HELP (Help - not in error state) 
X'F4' ROLLDOWN (Page Down) 
X'F5' ROLLUP (Page Up) 

X'F6' PRINT (Print) 

X'F8' HOME (Record Backspace) 
Mouse Buttons—Benefits 


Mouse buttons can be used for such things as reordering the layering of windows 
and selecting objects. For example, an application programmer can program 
middle button down as a single event AID to enable window reordering when mul- 
tiple windows are on a display. When the user presses the middle button, the 
cursor moves to the pointer device cursor location and the host-defined AID is 
returned. The application uses the host-defined AID to recognize a reorder 
request. If the row and column cursor address indicates that the pointer device 
event occurred within an overlaid window, the windows can be reordered. If the 
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Programmable 


row and column cursor address indicates that the pointer device event did not 
occur within an overlaid window, the application can ignore the AID or post a 
message. 


Note: If the EVENT IDs (E00-E15) are used, you may consider defining equivalent 


functions to be performed using the keyboard. For example, you may allow 
the user to position the text cursor and press a function key to perform a 
function equivalent to pressing a mouse button. This would enable func- 
tions on displays attached to controllers that do not support an enhanced 
interface for nonprogrammable work stations and on nonprogrammable dis- 
plays without pointer devices. 


Mouse Buttons Operation 


When a pointer device event is performed that has been programmed as a single 
event and no other function has higher priority, the following occurs: 


{ 


. The keyboard is locked (as it is for function keys). 
2. The cursor is moved to the pointer device cursor location. 

3. 

4. If the AID or moving the cursor normally results in validation of entry field data, 


The specified AID is returned to the host. 


the data is validated. 


. If the specified AID normally returns inbound entry field data, inbound entry 


field data is included. The format of the inbound data is like typical inbound 
data. 


. Control is returned to the application. 


There will be no way for the application to differentiate between the pointer 
device event and the corresponding command key. However, the pointer 
device event may be associated with an EVENT ID (E00-E15) that is not also 
associated with any command key. This provides a way to detect a pointer 
device event. 


When a two event pointer device event is performed, the system looks for the 
leading edge event. When the leading edge event is received, the following occurs: 


Note: Inbound data is not returned until the trailing edge event occurs. 


dl 
2. 


3. 


4. 


A programmable-two-event state is entered. 

A marker box is drawn around the location of the pointer device cursor on non- 
programmable work stations capable of displaying a marker box. The marker 
box appears as 4 blue lines around the character. 

The pointer device color is changed to white on nonprogrammable work 
stations capable of displaying white. 

The system looks for the trailing edge event. 


Keystrokes and host data streams will cancel the programmable-two-event state. 

Some pointer device events are ignored while waiting for the trailing edge event. 

For more information, see “Programmable Mouse Buttons—NWS Considerations” 
on page 6-72. When the trailing edge event is received, the following occurs: 


1. The marker box is erased 

2. The pointer device cursor color is changed to input inhibited 

3. The keyboard is locked 

4. The text cursor is moved to the location of the pointer device cursor 


If the specified host-defined AID normally returns inbound entry field data, 
inbound data is included. The ending row and column location is returned. 


Chapter 6. Creating a Graphical Look for Displays 6-71 


Note: The RTNCSRLOC keyword can also be used to retrieve the starting 
location of the cursor. This may be different from the ending cursor 
location when using a two event definition. 


Using programmable mouse buttons can prohibit other pointer device functions on 
the display. For example, the copy and paste function has a lower priority than the 
programmable mouse buttons for the shifted left button press and release. For 
more information on the priority of pointer device events, see “Programmable 
Mouse Buttons—Event Processing Priority” on page 6-73. 


Programmable Mouse Buttons—NWS Considerations 
Many of the pointer device events result in either the text cursor being moved or an 
AID being sent to the host. If the text cursor was in an entry field, entry field 
requirements (for example, mandatory fill) are checked before the text cursor is 
allowed to move or an AID is sent. This could result in an error code being posted 
and the pointer device event would not be processed. For example, the 0014 error 
code may be posted indicating that a mandatory fill field contains a null. 


The NWS passes an event to the system any time a button is pressed or released. 
It passes a double-click event to the system if a button is pressed, released, and 
pressed again within a user-specified double click time. The system sees a button 
pressed event, button released event, and a double click event, and eventually a 
button released event. 


A pointer device event will be ignored by the system if any of the following are true: 


e The keyboard is locked. An exception is single event programmable mouse 
buttons which can be defined to be queued if the keyboard is locked. 


e The keyboard is in system request state or ss message state. 


e¢ The keyboard is in operator error state. An exception is the left button down 
and shifted left button down which can reset an operator error. 


e The display is in WP mode. 
e¢ The system has any stored type ahead keystrokes. 


e The system does not have a pending read. An exception is single event pro- 
grammable mouse buttons. When the keyboard is unlocked, the system 
normally has a pending read. However, 3270DE sometimes unlocks the key- 
board without a pending read. Processing a pointer device event could be con- 
fusing in this case. 


Programmable Mouse Buttons—Event Processing States 


Pointer device event processing can be in various states. The following events, 
when received in an unexpected state, cause the state of the pointer device event 
processing to be reset: 


e¢ Most mouse button events (except as noted) 
e¢ Most keyboard events (not shift key make/break, for example) 
¢ All host display updates 

The state is reset as follows: 


e If the scroll bar drag and drop state is active, the drag and drop state is reset 
and the scroll bar is re-written to the original state. 
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e lf the copy and paste state is active, the copy and paste state is reset and the 
ending point indication is removed from the display. 


e lf the programmable mouse buttons two-event state is active, the state is reset 
and no AID is posted. The follow events are ignored in the two-event state so 
as not to reset the state when that would not be the desired effect: 


— A mouse button release event associated with the leading edge event. 


— A mouse button press event which must be generated to get to the trailing 
edge event. The trailing edge must be the button release or double click 
on the same button and shift state. 


— A mouse button release event which must be generated to get to the 
trailing edge event. The trailing edge must be the double click on the same 
button and shift state. 


Mouse button events which cause states to be reset are not processed any further. 
Keyboard events and host screen updates are processed as usual after resetting 
any mouse event processing state. 


Programmable Mouse Buttons—Event Processing Priority 
This section describes the event processing priorities for the following events: 


e Unshifted left button pressed 

e Unshifted left button released 

e Unshifted left button double clicked 
e Shifted left button pressed 

e Shifted left button released 

¢ Shifted right button pressed 

e All other events 


Unshifted Left Button Pressed Event Processing 

If the shift key is not down and the system receives a left button pressed event, the 
system determines the position of the pointer device cursor and performs exactly 
one of the following functions, checking in the order listed: 


1. If an operator error is on the display, the pointer device cursor can be used to 
reset the operator error. Depending on the position of the pointer device 
cursor, one of the following functions is performed: 


a. If the pointer device cursor is on the operator error line, then the same 
function is performed as if the user pressed the Reset key. The reset func- 
tion is also performed if the pointer device cursor is on the last line of the 
display and the separately displayable operator error line line is being used 
(line 25 or line 28). 


b. Otherwise, the pointer device event is ignored and the following checks are 
not done. 


2. If the pointer device cursor is on a selection field choice: 


a. If the choice is a cursorable choice, the cursor is moved to the location of 
the pointer device cursor. A selection cursor is created. The function of a 
Spacebar key is performed (this includes posting operator error 0084 if the 
choice is unavailable). The cursor must be somewhere between the first 
text attribute and the last text attribute in the choice. If selection indicators 
are used, the cursor must be somewhere between the selection indicator 
attribute and the last text attribute in the choice. 
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b. If on a noncursorable or null choice, the cursor is not moved and operator 
error 0084 is posted. 


3. If the pointer device cursor is on a scroll bar character (arrow character or shaft 
character), a roll AID may be sent to the host. If a roll AID is sent to the host 
the field MDT is set on. The text cursor may be moved to the position of the 
pointer device cursor. This depends on one of the following: 


e The setting of the "move the cursor to the scroll bar on a pointer device 
interaction" flag in the Define Scroll Bar command 

e The position of the cursor if this scroll bar is associated with a selection 
field 


The keyboard is locked (as if the user pressed a normal AID key). 


a. If the pointer device cursor is in the shaft above the slider, a Roll Down AID 
with a scroll increment of X'00000000' is sent to the host. Similarly, if the 
pointer device cursor is in the shaft below the slider, a Roll Up AID is sent. 

b. If the pointer device cursor is on the top arrow character and the slider is 
not already at the top of the scroll bar, a Roll Down AID with a scroll incre- 
ment of X'00000001' is sent to the host. Similarly, if the pointer device 
cursor is on the bottom arrow character and the slider is not already at the 
bottom of the scroll bar, a Roll Up AID with a scroll increment of 
X'00000001 ' is sent to the host. If the pointer device cursor is on the top 
arrow character and the slider is already at the top of the scroll bar, the left 
button pressed is ignored. The bottom arrow character functions similarly. 

c. If the pointer device cursor is on the slider, a drag and drop function should 
be started (scroll bar slider drag and drop state). The NWS is told to pass 
pointer device cursor movement to the system. In scroll bar drag and drop 
state, for each movement event, the system calculates the row of the 
pointer device cursor and compares this value with the last row which was 
processed. If the row values are different, the scroll bar characters are 
re-written. The slider is re-positioned within the shaft. If the pointer device 
cursor moved up one row, the slider is moved up one row. If the pointer 
device cursor is moved up more rows than exist in the shaft above the 
slider, the slider is moved to the top of the scroll bar shaft. When the left 
button is released, the drop function is performed; see Left Button 
Released for a description of the roll AID request. If any pointer event 
other than left button released occurs, or if any keyboard key is pressed, or 
if any screen update is done by the host, the following occurs: 

e The scroll bar characters are re-written to their original state 
e The scroll bar slider drag and drop state is reset 

¢ No roll AID is sent 

e The MDT is not set 


4. If the pointer device cursor is in a light pen field (first field position through the 
last field position), the system treats the event as if a light pen tip switch were 
activated at the position of the pointer device cursor. 


5. If this mouse button event has been programmed with the Programmable 
Mouse Buttons structured field, the event is handled as described above. 


6. If the pointer device cursor is on a simple hot spot, a hot spot function is per- 
formed. Hot spots enable a pointer device to partially drive older applications. 
In order to be considered a hot spot, the pointer device cursor must not be in 
an entry field. The hot spot functions for unshifted left button pressed events 
are: 
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¢ Command Key emulation. For more information, see “Command Key 
Emulation” on page 6-68. 


e Page Up and Page Down Key Emulation. For more information, see “Page 
Up and Page Down Key Emulation” on page 6-69. 


e Enter key emulation. For more information, see “Unshifted Left Button 
Double Click Event Processing.” 


7. If pull-down cancel mode is active, the cursor is moved to the position of the 
pointer device cursor, the keyboard is locked (treated like a normal AID), and 
the specified AID is returned to the host. Pull-down cancel mode is active if a 
selection field was written to the display and a Pull-Down Cancel AID was 
specified in the Define Selection Field major structure. 


Note: Pull-down cancel mode is lower priority than hot spots because pull- 
down menus could have command keys or More -/+ inside them. 


8. Otherwise, the cursor is moved to the location of the pointer device cursor. 
The cursor could be a text cursor or a selection cursor (for a highlighted entry 
field). The system allows the text cursor to move to a noncursorable text 
location even if cursor movement to input-capable positions only is set on. 


Unshifted Left Button Released Event Processing 

If the shift key is not down and the system receives a left button released event, 
the system determines the position of the pointer device cursor and performs 
exactly one of the following functions, checking in the order listed: 


1. If scroll bar slider drag and drop state is active, the scroll bar characters may 
be updated. For more information on scroll bars, see “Unshifted Left Button 
Pressed Event Processing” on page 6-73. If the row position of the pointer 
device cursor is different than the row position when the slider was last written, 
the scroll bar characters should be written. If the final slider position is different 
than the original slider position (when the drag and drop was started), the fol- 
lowing occurs: 


a. The MDT is set on 
b. The text cursor may be moved to the scroll bar slider 


c. A Roll AID is sent to the host with a scroll increment indicating the number 
of rows or columns to be scrolled 


d. The keyboard is locked (treated like a normal AID) 


The specific AID depends on the direction the slider moved. If the slider did 
not move, no AID is sent. In all cases, the scroll bar slider drag and drop state 
is reset. 


2. If this mouse button event has been programmed with the Programmable 
Mouse Buttons structured field, the event is handled as described above. 


3. Otherwise, the pointer device event is ignored. 


Unshifted Left Button Double Click Event Processing 

If the shift key is not down and the system receives a left button double click event, 
then the system determines the position of the pointer device cursor and performs 
exactly one of the following functions, checking in the order listed: 


1. If this mouse button event has been programmed with the Programmable 
Mouse Buttons structured field, the event is handled as described above. 
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2. Otherwise, if the previous left button pressed event simply positioned the 
cursor, the keyboard is locked and the Enter AID is sent to the host. This is a 
hot spot function. 


3. Otherwise, the unshifted left button double click event is ignored. 
Note: The user must have done one of the following: 


¢ Selected a selection field choice 

¢ Operated against a scroll bar 

¢ Caused a pointer device selectable AID 

¢ Selected a hot spot (for example, a command key) 

¢ Caused some other left button pressed event function, other than 
the default action of simply positioning the cursor. 


Shifted Left Button Pressed Event Processing 

If the shift key is down and the system receives a left button pressed event, the 
system determines the position of the pointer device cursor and performs exactly 
one of the following functions, checking in the order listed: 


1. If an operator error is on the display, the pointer device cursor can be used to 
reset the operator error. Depending on the position of the pointer device 
cursor, one of the following functions is done: 


a. If the pointer device cursor is on the operator error line, then the same 
function is performed as if the user pressed the Reset key. The reset func- 
tion is also performed if the pointer device cursor is on the last line of the 
display and the separately displayable operator error line line is being used 
(line 25 or line 28). 


b. Otherwise, the pointer device event is ignored and the following checks are 
not performed. 


2. If this mouse button event has been programmed with the Programmable 
Mouse Buttons structured field, the event is handled as described above. 


3. Otherwise, a copy and paste function (frequently called cut and paste) is 
started. The copy and paste state is set. The location of the pointer device 
cursor is marked to indicate an end point of the select. A line is drawn above 
and below the character location of the pointer device cursor. If any other 
pointer device event other than shifted left button released occurs, or the user 
presses any key, or any data is received from the host, the copy and paste 
state is reset and the two lines are removed. When the shifted left button is 
released, copy and paste processing continues (see “Shifted Left Button 
Released Event Processing”) for later use in a paste operation (see “Shifted 
Right Button Pressed Event Processing” on page 6-78). 


Shifted Left Button Released Event Processing 

If the shift key is held down and the system receives a left button released event, 
the system determines the position of the pointer device cursor and performs 
exactly one of the following functions, checking in the order listed: 


1. If copy and paste state is active, the user has now marked the second end 
point of the copy. The second end point is marked by drawing three lines 
around the second end point and adding one line around the first end point. 
This looks like square brackets enclosing the copy data. The user can mark 
either the starting or ending point first. Then, the marked copy data is stored in 
the display (for example, 348X NWS) for later use (see “Shifted Right Button 
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Pressed Event Processing” on page 6-78). For performance reasons, the copy 
and paste data will be copied from the display to the system-managed buffer in 
the display (without crossing the twinaxial cable). Some formatting may be 
done by the system to the copy and paste data after the data has been copied 
within display memory: 


e If the display is a SBCS display (not capable of DBCS) and the data was 
copied from a non-display area, the system writes a non-display attribute 
over the first position of the copy and paste data. A non-display area is an 
area in which a non-display attribute was in effect for the copy and paste 
data. 


e If the display is a DBCS display, but not capable of DBCS-pure fields, the 
following formatting takes place: 


Note: Support for DBCS-pure fields includes supports extended SO/SI 
attributes which do not require a screen position. 


— If the first byte of copy and paste data is DBCS data (preceded by a 
SO character) and the starting point of the DBCS data is the second 
byte of a DBCS character, the starting point of the copy is decreased 
by one position (to include the entire character). 


— If the last byte of copy and paste data is DBCS data and the ending 
point of the DBCS data is the first byte of a DBCS character, the 
ending point of the copy is increased by one position (to include the 
entire character). 


— If the first byte of copy and paste data is DBCS data (preceded by a 
SO character), the system writes an SO ahead of the first byte of copy 
and paste data. 


— If the last byte of copy and paste data is DBCS data, the system writes 
an SI after the last byte of copy and paste data. 


— lf the data was copied from a non-display area, the system writes a 
non-display attribute over the first non-SO/SI character in the copy and 
paste data. If the character in the copy and paste data is a DBCS 
character, the system writes two non-display attributes over the first two 
non-SO/SI characters. 


The end point indications on the display should be reset when one of the fol- 
lowing occurs: 


e Any key is pressed other than the four cursor movement keys. The system 
allows the user to move the text cursor without resetting the end points. 


e Another pointer device event occurs. 
e The host updates the display. 


The copy and paste data is lost only when the NWS powers down or the user 
completes the copy portion of another copy and paste operation. 


. If this mouse button event has been programmed with the Programmable 
Mouse Buttons structured field, the event is handled as described above. 
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Shifted Right Button Pressed Event Processing 
The system performs exactly one of the following functions, checking in the order 


listed: 


1. If this mouse button event has been programmed with the Programmable 
Mouse Buttons structured field, the event is handled as described above. 


2. If the system receives a right button pressed event and the user has previously 
selected data for a copy and paste operation, the system auto-keys the 
selected data at the location of the text cursor. This is done independently of 
the location of the pointer device cursor. The system performs the following 
steps: 


If the text cursor is not in an entry field, operator error X'0005' is posted. 


The copy and paste data is read from the display into main storage. The 
length of the data read is the smaller of the length of the copy and paste 
data, and the length of data which will fit into the entry field. 


Note: Continued fields are considered a single entry field. 


Data following a non-display attribute is converted to blanks, until another 
non-display attribute is found. 


Attributes are converted to blanks. 
GUI-like characters are converted to blanks. 
Nulls are converted to blanks. 


The system will perform all normal field checks (for example, digits only, 
alphanumeric only, and so on). This could result in an operator error. If an 
operator error is posted, no data following the point of the error is pasted. 


If the field is a monocase field, the data is monocased. 


If the display is a DBCS display and the field is a DBCS field, the following 
processing takes place: 


— If the field is a DBCS-only field, the copy and paste data must begin 
with an SO (otherwise, operator error "0092" is posted). The DBCS 
characters are placed into the field until the field ending SI is found, or 
an Sl is found in the copy and paste data. The SO and SI characters 
are not pasted. 


— If the field is a DBCS-either field, the copy and paste data must be the 
proper format or operator error 0092 is posted. Operator error 0092 
indicates that either no SO character is allowed (if the field is SBCS), or 
that the data must start with an SO character (if the field is DBCS). 
DBCS paste is just like describe above for a DBCS-only field. 


— If the field is a DBCS-pure field, the copy and paste data must begin 
with an SO (otherwise, operator error "0092" is posted). The DBCS 
characters are placed into the field until the end of the field is found, or 
an Sl is found in the copy and paste data. The SO and SI characters 
are not pasted. 


— If the field is a DBCS-open field, the copy and paste data is auto-keyed 
into the field. If the copy and paste data starts with an SO character, 
the SO is pasted if the cursor is under a DBCS character. If the cursor 
is under an SBCS character, the SO is not pasted. If the copy and 
paste data does not start with an SO character, an SI will be pasted if 
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the cursor is under a DBCS character. If the last character in the field 
is a DBCS character, the system will reserve room for an SI after the 
last DBCS character. 


e If the user is in replace mode and the paste data is too long to fit in the 
entry field, as much data is placed in the field as possible, the cursor is 
placed in the last position of the entry field, and operator error 0012 is 
posted. 


e If the user is in insert mode and the paste data requires more positions 
than the number of nulls at the end of the entry field, as much data is 
placed in the field as possible, the cursor is placed on the last export char- 
acter, and operator error 0012 is posted. 


Note: The copy and paste data is never reset. The user is allowed to paste 
the most recent copy and paste data multiple times. 


3. If the user has not previously selected data for a copy and paste operation, the 
system will ignore the event. 


Any Other Pointer Device Event Processing 
1. If the mouse button event has been programmed using the Programmable 
Mouse Buttons structured field, the event is handled as described above. 


2. Otherwise, the event is ignored. 


Grid Line Structures—Overview 


Grid line structures include horizontal lines, vertical lines, and boxes. They can 
only be displayed on DBCS display stations. For details on the required hardware, 
see “Hardware Requirements for Grid Line Structures” on page 6-82. An example 
of grid line structures appears in Figure 6-60 on page 6-80. 


The grid line keywords also allow you to do the following: 


e Clear grid lines within a specified rectangle 
e Erase a specified grid line structure 
¢ Control the attributes of grid line structures such as color and line type 
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FIELD 1 


FIELD 2 


Figure 6-60. Grid Line Structures 


DDS for Grid Line Structures—Example 
The DDS in Figure 6-61 creates the grid line structure in Figure 6-60. 


| cegtacive langehysga2esethene ad ie chores dey eekiy bebveweti venOuetets cael eas 


A GRDATR((*COLOR BLU) (*LINTYP SLD)) 
A 

A R GRDREC GRDRCD 

A 96 GRDCLR 

A GRDBOX((*POS (3 10 4 20)) + 
A (*TYPE PLAIN) + 

A (*COLOR RED) (*LINTYP THK) + 
A (*CONTROL &CNTL1)) 

A 

A GRDBOX((*POS (10 2 10 60)) + 
A (*TYPE HRZVRT 2 15) + 

A (*CONTROL &CNTL2) ) 

A CNTL1 1S OP 

A CNTL2 1S OP 

A 

A R REC1 

A 

A FIELD1 7A B15 5SCHGINPDFT 

A 

A FIELD2 7A B 18 35CHGINPDFT 


Figure 6-61. DDS for Grid Line Structures—Example 
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Notes: 


1. It is recommended to add a CHGINPDFT keyword to an input/output field when 
a grid line structure is defined directly under the field. 


2. In general, grid line structures are written in the order that they are coded in the 
display file. 


3. If a display file is created or changed to nonenhanced display (ENHDSP *NO), 
no grid line records are written to the display. 


When record GRDREC is written with option indicator 96 on, the GRDCLR keyword 
causes all grid line structures on the screen to be cleared. The remainder of the 
keywords are then processed in the order that they are coded. If the program-to- 
system field CNTL1 contains a 1, the first GRDBOX keyword is ignored. If CNTL1 
contains 0, a PLAIN box grid is displayed. This box begins at row 3, column 10. It 
has a depth of 4 rows and a width of 20 columns. The box has a thick line type 
and is red. If CNTL1 contains -1, the grid line structure at the defined position is 
erased and all other grid line structures on the display are left intact. 


If the program-to-system field CNTL2 contains 1, the second GRDBOX keyword is 
ignored. If CNTL2 contains 0, a horizontally and vertically ruled box is displayed. 
This box begins at row 10, column 2. It has a depth of 10 rows and a width of 60 
columns. The box has a horizontal rule every 2 rows and a vertical rule every 15 
columns. Because there are no attributes defined on the GRDBOX keyword, the 
attributes default to those defined on the GRDATR keyword at the file level. These 
attributes are a solid line type and color blue. If CNTL1 contains -1, the grid line 
structure at the defined position is erased and all other grid line structures on the 
display are left intact. 


Grid line structures are defined in records separate from other data fields. Grid line 
records are displayed independent of all other data records. Grid line records are 
also cleared independent of other data records. If the device file has 
DFRWRT(*YES), all records written are buffered until a GET operation is done. 
This includes all grid line records. A READ or PUTGET operation cannot be done 
to a grid line record because there is no possible input for the grid line record. The 
FRCDTA keyword is allowed on grid line records. In this case, the grid line record 
written is immediately displayed regardless of the DFRWRT keyword. 


Grid Line Structures and Windows 


If a grid line structure is on the display when a GUI window is displayed, the con- 
troller removes all grid lines under the window prior to displaying the window. If 
grid lines are on the display when a non-GUI window (for example, a UIM help 
window) is displayed, all grid lines are removed from the display. When the 
window is removed from the display, the display is restored including all grid line 
structures. 


A grid line record can define a window or specify a window reference record. 

When a grid line structure is defined with a window, all start- row and start-column 
parameters are relative to the start of the window. This includes both the start-row 
and start-column parameters defined with DDS and the start-row and start-column 
values set at run time with program-to-system fields. A grid line structure can be 
displayed outside of the window. The depth, width, and length parameters will trun- 
cate to the end of the display if they are too large for the display size. 
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If a window is displayed, writing a grid line record to the base display causes the 
window to be removed unless the USRRSTDSP keyword is defined on the window 
record. The base screen is restored prior to displaying the grid line structures. 


Hardware Requirements for Grid Line Structures 
Grid line support requires DBCS hardware. This hardware should have the capa- 
bility of running Japanese DOS. Japanese DOS is supported by the following 
PS/55 systems: 


e 5523-S, 5523-V, 8551-S 

e 5535-S (laptop) 

e 5530-T/V/W, 5541-T, 5551-S/TV/W, 5561-W (desktop) 
e 5571-T/V, 5580-W/Y (floorstanding model) 


Note: PS/1* and PS/2* systems do not support Japanese DOS. 


For the desktop and floorstanding PS/55 systems, the Japanese keyboard 
(5576-001/002/003/A01) and DBCS-capable display (5574) are required. The 5530 
system has an integrated display. As a twinaxial communication adapter, 5250 
adapter/A (ID#65X1092) is required. 


The AS/400 system can sense if the attached display is capable of displaying grid 
line structures. If a grid line record is written to a display that does not support grid 
line structures, the record is ignored. However, window keywords on the grid line 
record are processed. 


Grid line structures (nonfield level file) can be printed using the Print Screen key if 
the printer supports DBCS. 


Inserting HTML Tags 


The World Wide Web (or Web for short) is a graphical interface that provides 
access to an enormous amount of information available on the Internet. The Web 
allows Internet users to access documents that contain text and non-text objects 
(such as video, sound, graphics, and so on). The documents can contain “links” 
(hyperlinks) to other documents that may also contain links to other documents. 
The text within a Web document that contains hyperlinks is called hypertext. The 
chain of reference from document to document is virtually endless since all docu- 
ments can link to other documents. 


You can tailor documents on the Web to present multimedia information from a 
variety of sources allowing end users to optionally access the information identified 
by the links. 


DDS support of the AS/400 5250 Workstation Gateway allows you to change 
existing applications to enable them for the Internet through the World Wide Web. 
The AS/400 5250 Workstation Gateway translates all 5250 data streams to an 
HTML (Hypertext Markup Language) document and exports the document from 
AS/400. You can insert HTML tags into a display file that allow graphic capabilities 
of the client web browser to be utilized with only minor changes to the display file 
source. 


The HTML keyword is given a row/col position in the DDS file. However, row and 
column positioning has no meaning in an HTML document. The row and column in 
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the display file determines the order of HTML tags in the HTML document that is 
created. For example, an HTML keyword at row 2/column 4 appears before an 
HTML keyword with a row 2/column 6 position. HTML keywords with the exact 
same row and column position will be placed into the HTML document in the same 
order in which they are defined in the DDS file. 


Resolving HTML Field Overlap 


The following examples show where the HTML will appear when you use the fol- 
lowing coding: 


Example 1 


The HTML field has a starting column 2 before an output field. The HTML will 
appear before the field. 


A 01 FLDIA 20 015 7DFTVAL('Output Field') 
A 01 15 SHTML('<p>HTML code') 


will result in: 
HTML code 
Output Field 


Example 2 


The HTML field has a starting column 1 before an output field, meaning that the 
HTML starts at the attribute byte of the output field. The HTML will appear before 
the field. 


A 01 FLDIA 20 O15 6DFTVAL('Output Field') 
A 01 15 SHTML('<p>HTML code') 


will result in: 
HTML code 
Output Field 


Example 3 


The HTML field has a starting column equal to an output field. The HTML will 
appear before the first character of the field. 


A 01 FLDIA 20 O15 6DFTVAL('Output Field') 
A 01 15 6HTML('<p>HTML code') 


will result in: 
HTML code Output Field 


Example 4 


The HTML field has a starting column 1 past the starting column of an output field. 
The HTML will appear after the 1st character of the output field. 


A 01 FLDIA 20 015 6DFTVAL('Output Field') 
A 01 15  7HTML('<p>HTML code') 


will result in: 
OHTML codeutput Field 


Example 5 
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The HTML field has a starting column 1 past the ending column of an output field, 
meaning that it overlaps the ending attribute. The HTML will appear after the last 
character of the output field. 


A 01 FLDIA 20 015 6DFTVAL('Output Field') 
A 01 15 27HTML('<p>HTML code') 


will result in: 
Output FieldHTML code 


Example 6 


The HTML field has a starting column 2 past the ending column of an output field. 
The HTML will appear after the output field. 


A 01 FLDIA 20 015 6DFTVAL('Output Field') 
A 01 15 28HTML('<p>HTML code') 


will result in: 
Output Field 
HTML code 


Notes: 


1. Merging of HTML and DDS fields does not occur for input fields. Merging 
occurs only for output fields. 


2. HTML tags are inserted into the data stream if the device query indicates that 
the device is an AS/400 5250 Workstation Gateway virtual terminal. Otherwise 
for normal displays, the HTML tags are ignored. 
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Programming Examples 


You can add the IMG HTML keyword to an existing display file and show a graphic 
image along with the display as the following examples show. 


Figure 6-62 shows an example of the DDS before adding HTML keyword 


: 
: 
: 
i 
: 
: 
: 
> 
: 


FILE LEVEL KEYWORDS 


DSPSIZ(24 80 *DS3) 
CA03 (03) 


R REC1 
CA01(01) 
CA02 (02) 
30'Description' 
DSPATR(HI) 
DSPATR(UL) 
13'Item' 
DSPATR(HI) 
DSPATR(UL) 
65'Price' 
DSPATR(HI) 
DSPATR(UL) 


on 


on 


on 


FLDQO1 10A 0 6 
FLDQO2 25A 0 6 30 
FLDQO3 6A 0 6 

1 


rFPrrrrrrrrrrrrrrrrrrrrrsSsy 


36'Catalog' 


Figure 6-62. DDS Coding Before Adding HTML Keyword 
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Figure 6-63 shows an example of the DDS after adding HTML Keyword 


; 
; 
: 
i 
: 
: 
: 
> 
: 


FILE LEVEL KEYWORDS 


DSPSIZ(24 80 *DS3) 
CA03 (03) 


R REC1 
CA01(01) 
CA02 (02) 
5 30'Description' 
DSPATR(HI) 
DSPATR(UL) 
5 13'Item' 
DSPATR(HI) 
DSPATR(UL) 
5 65'Price' 
DSPATR(HI) 
DSPATR(UL) 
FLDOO1 10A O 6 
FLDQO2 25A 0 6 30 
FLDQ03 6A 0 6 
7 2HTML('<img src="http://www.ice.com + 
/bin/sundae.gif') 
36'Catalog' 


rFPrrrrrrrrrrrrrrrrrrrrrrrTr,Yr 


— 


Figure 6-63. DDS Coding After Adding HTML Keyword 


On AS/400 5250 Gateway display stations, you would see the following graphic 
image if you used the DDS source in Figure 6-63: 


Catalog 
Item Description Price 
Ice Cream Chocolate Temptation 6.99 


at : 


RV3W133-0 


Figure 6-64. Graphic Image on an AS/400 5250 Gateway Display 
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-— Restrictions 
The 5250 Gateway reserves the F1 function key as General Help. F1 cannot 
be redefined for other uses. 


Due to limitations of the web browser, the 5250 Gateway does not support 
many of the graphic structures that DDS allows. 


The following keywords are allowed, but are not supported. Attempting to 
display them will have unpredictable results. 


Windows WINDOW keyword) 
Menubars MNUBAR keyword) 
Pulldown PULLDN Keyword) 


Selection Lists SFLMLTCHC/SFLSNGCHC keywords) 
SNGCHCFLD/MLTCHCFLD keywords) 
PSHBUTTON keyword) 

SCRBAR keyword) 


CNTENTFLD keyword) 


Selection Fields 
PushButtons 


Scrolibars 


ee ee eee eee eee eee 


Continued Entry Fields 
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Chapter 7. Overriding Display Files and Display File 
Attributes 


You can use overrides to temporarily change a file name, a device name associ- 
ated with the file, or some of the other attributes of a file. Overrides allow you to 
make minor changes to the way a program functions or to select the data on which 
it operates without having to recompile the program. 


Determining Whether or Not to Use Overrides 


The following properties of overrides will help you decide if overrides are appro- 
priate for the task you want to perform: 


¢ Overrides remain in effect only for the job, program, or display station session 
in which they are issued. They do not permanently change the attributes of a 
file. 


¢ Overrides have no effect on other jobs that may be running at the same time. 


¢ Overrides that are to be applied must be specified either before the file is 
opened by a program or before a program that opens the file is compiled. 


¢ Override commands may be entered interactively from a display station or as 
part of a batch job. 


¢ Override commands may be included in a control language (CL) program, or 
they may be issued from other programs via a call to the program QCMDEXC. 


¢ Overrides allow you to make minor changes to the way a program functions or 
for selecting the data on which it operates, without having to recompile the 
program. 


Overriding File Attributes in HLL Programs 
File attributes are built as a result of the following: 


Create file commands These commands build file attributes when the file is 
first created. 


Program using the files At compile time, the user program can specify some of 
the file attributes. (The attributes that can be specified 
depend on the high-level language in which the 
program is written.) 


Override commands At program run time, these commands can override the 
file attributes previously built by the merging of the file 
description and the file parameters specified in the user 
program. 


The simplest form of overriding a file in a high-level language (HLL) program is to 
override some attributes of the file using the Override with Display File (OVRDSPF) 
command. 


Example: You create a display file named DISPLAY33 using the Create Display 
File command: 


© Copyright IBM Corp. 1997 7-1 


CRTDSPF FILE(QGPL/DISPLAY33) SRCFILE(DDSFILE1) + 
DEV(STATION1) IGCDTA(*YES) WAITFILE(30) LVLCHK(*NO) 


Your application program specifies display file DISPLAY33 with STATIONS5O for the 
display station and *NO for the IGCDTA parameter, which determines double-byte 
character processing. 


Before you run the application program, you want to change the display station to 
STATION23 and wait file time to 45 seconds. The override command looks like 
this: 


OVRDSPF FILE(DISPLAY33) DEV(STATION23) WAITFILE(45) 


When the application program opens the file, the file overrides, program-specified 
attributes, and file attributes are merged to form the open data path (ODP), which is 
used during the running of the program to manage access to the file and to 
manage its attributes. File overrides have precedence over program-specified attri- 
butes. Program-specified attributes have precedence over file-specified attributes. 
In this example, when the file is opened, the following is used: 


¢ Display station STATION23 

e¢ A double-byte character processing value of *NO 

¢ Await file time of 45 seconds 

e The level identifiers of the records formats are not checked when the file is 
opened. 


The following illustration explains the previous example: 


Display 
Program A File DISPLAY33 


SRCFILE(DDSFILE1) 
DEV(STATION1) 
IGCDTA(*YES) 
WAITFILE(30) 
LVLCHK(*NO) 


. | 
Open 
DISPLAY33 


Program-Specified 
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Attributes Open Data Path 
| DEV(STATIONSO) SRCFILE(DDSFILE1) 
IGCDTA(*NO) DEV(STATION23) 
\ 3 / IGCDTA(*NO) 
WAITFILE(45) 
| LVLCHK(*NO) 


Override Command 


| DEV(STATION23) 
| WAITFILE(45) 


RV2W016-3 


Overriding File Names in HLL Programs 


Another simple form of overriding a file in a high-level language program is to 
change the file that is used by the program. This may be useful for files that have 
been moved or renamed after the program has been compiled. Use the OVRDSPF 
command for file name overrides also. 


Example: You want the output from your application program to be displayed 
using the display file DISPLAY12 instead of the display file DISPLAY33 
(DISPLAY33 is specified in the application program). Before you run the program, 
enter the following: 


OVRDSPF FILE(DISPLAY33) TOFILE(DISPLAY12) 


The file DISPLAY12 must have been created by a CRTDSPF command before it 
can be used. 


The following illustration explains the previous example: 


Display 
file 
DISPLAY33 DISPLAY33 output 
Program 
Before : 
Override: Use display file DISPLAY33_. ———»> ra 
Record 
format RV2W006-2 
Display DISPLAY33 output 
Program file ——eees 
. DISPLAY 
After . = el = ae 
Override: Use display file DISPLAY33 | | 
. | | 
Display I Cae" FS) 
file r 
DISPLAY12 | | DISPLAY12 output 
. 1 a 
J J 
Record / ee os 
format 


RV2W007-2 


You may want to override a file with a file that has a different file type; for example, 
you may want to override a display file with a diskette file using the Override 
Diskette File (OVRDKTF) command. To determine if your file can be overridden 
with a file that has a different file type, see the information under “Using File Redi- 
rection to Override File Names and Libraries or File Types” on page 7-6. More 
information about overriding with different file types is available in the Data Man- 
agement book. 


Overriding Both File Names and Attributes in HLL Programs 


This form of overriding a file in a high-level language program is simply a combina- 
tion of overriding file attributes and overriding file names or types. With this form of 
override, you can override the file that is to be used in a program and you can also 
override the attributes of the overriding file. Use the OVRDSPF command to over- 
ride both the display file name and attributes. 
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Example: You want the output from your application program to be displayed 
using the display file REPORTS instead of the display file OUTPUT. (OUTPUT is 
specified in the application program.) In addition to having the application program 
use the display file REPORTS, you wish to override the wait file time to 50 
seconds. 


Assume the file REPORTS was created with the following command: 
CRTDSPF FILE(REPORTS) SRCFILE(DDSFILE1) SRCMBR(MEMBER1) WAITFILE(25) 


Before you run the program, type the following command: 
OVRDSPF FILE(OUTPUT) TOFILE(REPORTS) WAITFILE(50) 


Then call the application program. The display file REPORTS is used with a wait 
file time of 50 seconds. 


Note that the single override command used in the previous example is not equal 
to the following two override commands: 


Override 1 OVRDSPF FILE(OUTPUT) =TOFILE(REPORTS) 
Override 2. OVRDSPF FILE(REPORTS) WAITFILE(50) 


Only one override is applied for each call level for an open operation of a particular 
file. If you want to override the file that is used by the program and also override 
the attributes of the overriding file from one call level, you must use a single 
command. If two overrides are used, override 1 causes the output to be displayed 
using the display file REPORTS, but override 2 is ignored. 


Applying Overrides When Compiling a Program 


Overrides may be applied at the time a program is being compiled for either of two 
purposes: 


¢ To select the display file 
¢ To provide external data definitions for the compiler to use in defining the 
record formats to be used on I/O operations 


Overrides to the source file are handled just like any other override. They may 
select another file, another member of a database file, or change other file attri- 
butes. 


Overrides may also be applied to files that are used within the program being com- 
piled, if they are being used as externally described files in the program. These 
files are not opened at compile time, and thus the overrides are not applied in the 
normal manner. These overrides are used at compile time only to determine the 
file name and library that will be used to define the record formats and fields for the 
program to use I/O operations. Any other file attributes specified on the override 
are ignored at compile time. It is necessary that these file overrides be active at 
compile time only if the file name specified in the source for the program is not the 
file name that contains the record formats that the application needs. 


The file name that is opened when the compiled program is run is determined by 
the file name that the program source refers to, changed by whatever overrides are 
in effect at the time the program runs. The file name used at compile time is not 
kept. The record formats in the file that is actually opened must be compatible with 
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those used when the program was compiled. Obviously, the easiest way to assure 
record compatibility is to have the same overrides active at run time that were 
active at compile time. If your program uses externally described data and a dif- 
ferent field level file is used at run time, it is usually necessary to specify 
LVLCHK(*NO) on the override. See “Using File Redirection to Override File Names 
and Libraries or File Types” on page 7-6 for details. 


Example: Assume that the source for the program INVENTORY, which has a wait 
file time of 15 seconds, contains an open to the display file LISTOUT: 


Override 1 OVRDBF FILE(RPGSRC) TOFILE(SRCPGMS) MAXRCDLEN(77) 
Override 2. OVRDSPF FILE(QUTPUT) TOFILE (REPORTS) 
CALL PGM(A) 


Program A 
Override 3 OVRDSPF FILE(LISTOUT) TOFILE (OUTPUT) 
Override 4 OVRDBF FILE(RPGSRC) WAITFILE(30) 
CRTRPGPGM PGM(INVENTORY) SRCFILE(RPGSRC) 
RETURN 


Override 5 OVRDSPF FILE(LISTOUT) TOFILE(REPORTS) IGCDTA(*YES) 
CALL PGM( INVENTORY) 


The program INVENTORY opens the display file REPORTS in place of display file 
LISTOUT and allows DBCS data. 


The program INVENTORY is created (compiled) from database file SRCPGMS and 
allows a maximum record length of 77 characters. Override 4 (applied first) over- 
rides an optional file attribute. Override 1 (applied last) causes the file RPGSRC to 
be overridden with the database file SRCPGMS and a maximum record length of 
77 characters. 


The program INVENTORY is created with the display formats from the file 
REPORTS. Override 3 (applied first) causes the file LISTOUT to be overridden 
with OUTPUT. Override 2 (applied last) overrides OUTPUT with REPORTS. Other 
attributes may be specified here, but it is not necessary because only the record 
formats are used at compile time. 


At run time, override 3 is no longer active, because program A has ended. There- 
fore override 2 has no effect on LISTOUT. However, override 5, which is active at 
run time, replaces LISTOUT with REPORTS and allows DBCS data. Because the 
same file is used for both compilation and run-time, level checking may be left on. 


Deleting Overrides 


If you want to delete an override, you can use the Delete Override (DLTOVR) 
command. 


If you use the DLTOVR command in an application that either calls or transfers 
control to other programs, the override may or may not be deleted. More informa- 
tion about deleting overrides in application programs is available in the Data Man- 
agement book. 
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Displaying Overrides 


You can display all file overrides or file overrides for a specific file using the Display 
Override (DSPOVR) command. 


If you use the DSPOVR command to display the overrides used by an application 
that either calls or transfers control to other programs, you can control which over- 
rides are displayed. More information about displaying overrides used in applica- 
tion programs is available in the Data Management book. 


Using File Redirection to Override File Names and Libraries or File 


Types 


File redirection refers to using overrides to change the file name and library or the 
type of the file to be processed. For example, you can substitute one display file 
for another or change from using an ICF file to using a display file. The system 
may or may not support file redirection. Refer to “Recognizing Commands That 
Ignore or Restrict Overrides” on page 7-9 for rules on how the system processes 
overrides. 


Overriding Files with the Same File Types 


When you replace the file that is used in a program with another file of the same 
type, the new file is processed in the same manner as the original file. If a field 
level file, or any other file containing externally described data is redirected, it 
usually is necessary to either specify LVLCHK(*NO) or recompile the program. 
With level checking turned off, it is still necessary that the record formats in the file 
be compatible with the records in the program. If the formats are not compatible, 
the results cannot be predicted. 


Overriding Files with Different File Types 


If you change to a different type of file, the device-dependent characteristics are 
ignored and records are read or written sequentially. Some device parameters 
must be specified in the new device file or the override. Defaults are taken for 
others. The effect of specific redirection combinations is described later in this 
section. 


Any attributes specified on overrides of a different file type than the final file type 
are ignored. The parameters SPOOL, SHARE, and SECURE are exceptions to 
this rule. They will be accepted from any override applied to the file, regardless of 
device type. 


Some redirection combinations present special problems due to the specific charac- 
teristics of the device. In particular: 


e File redirection is not recommended for save files. 


¢ Display files and ICF files that use multiple devices (MAXDEV or 
MAXPGMDEV > 1) can be redirected only to a display file or ICF file. 


e Redirecting a display file to any other file type, or another file type to a display 
file, requires that the program be recompiled with the override active if there are 
any input-only or output-only fields. This is necessary because the display file 
omits these fields from the record buffer in which they are not used, but other 
file types do not. 
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Table 7-1 on page 7-7 summarizes valid file redirections: 


Table 7-1. File Redirections 
From-File 
To-File Printer ICF Diskette Display Database Tape 
Printer O* O O oO oO O 
ICF ie) V/O 
oO O O oO oO O 
| | | | | 
Diskette oO O O oO oO O 
| I | | | 
Display ie) V0 
oO O oO oO oO O 
| | | | | 
Database oO O O oO oO O 
| I | | | 
Tape oO O O oO oO O 
| I | | | 
Legend: 
l=input file 
O=output file 
l/O=input/output file 
*=redirection to a different type of printer 


To use this chart, identify the file type to be overridden in the FROM-FILE columns 
and the file type overriding in the TO-FILE column. The intersection specifies an | 
or O or both, meaning that the substitution is valid for these two file types when 
used as input files or as output files. 


For instance, you can override a diskette output file with a tape output file, and a 
diskette input file with a tape input file. The chart refers to file type substitutions 
only. That is, you cannot change the program function by overriding an input file 
with an output file. 


The following chart describes the specific defaults taken and what is ignored for 
each redirection combination involving display files: 


Table 7-2 (Page 1 of 2). File Redirection Combinations 


From To Specific Defaults Taken and What Is Ignored 


Records are written to the display with each record 

overlaying the previous record. For program-described 

files, you can request each record using the Enter key. 
Printer Display Printer control information is ignored. 

Records are retrieved from the display one at a time. 

Type in the data for each record and press the Enter 


ICF input Display key when the record is complete. 
Records are written to the display with each record 
ICF output Display overlaying the previous record. 


Input records are retrieved from the display one ata 

time. Type in the data for each record and press the 

Enter key when the record is complete. Output records 

are written to the display with each record overlaying 

the previous input or output record. Input and output 

records are essentially independent of each other and 
ICF input/output Display may be combined in any manner. 
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Table 7-2 (Page 2 of 2). File Redirection Combinations 


From 


To 


Specific Defaults Taken and What Is Ignored 


Diskette input 


Diskette output 
Display input 


Display output 


Display 
input/output 


Database input 
(sequentially pro- 
cessed) 
Database output 
(sequentially pro- 
cessed) 


Tape input 


Tape output 
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Display 


Display 
ICF 


Diskette 
Database 


Tape 
ICF 
Database 


Diskette 


Tape 


Printer 


ICF 


Display 


Display 


Display 


Display 


Records are retrieved from the display one at a time. 
Type in the data for each record and press the Enter 
key when the record is complete. A non-field-level 
display file must be specified. Diskette label informa- 
tion is ignored. 

Records are written to the display with each record 
overlaying the previous record. You can request each 
output record using the Enter key. 

Records are retrieved from the ICF file one at a time. 
Records are retrieved in sequential order. Diskette 
label information must be provided in the diskette file or 
on an override command. 

Input records are retrieved. 

Records are retrieved in sequential order. Tape label 
information must be specified in the tape file or on an 
override command. 

Records are written to the ICF file one at a time. 
Records are written to the database in sequential order. 
The amount of data written on diskette is dependent on 
the exchange type of the diskette. Diskette label infor- 
mation must be provided in the diskette file or on an 
override command. 

Records are written on tape in sequential order. Tape 
label information must be specified in the tape file or on 
an override command. 

Records are printed and folding or truncating is per- 
formed as specified in the printer file. 


Input records are retrieved from the 

Records are retrieved from the display one at a time. 
Type in the data for each record and press the Enter 
key when the record is complete. A non-field-level 
display file must be specified. 

Records are written to the display with each record 
overlaying the previous record. You can request each 
output record using the Enter key. 

Records are retrieved from the display one at a time. 
Type in the data for each record and press the Enter 
key when the record is complete. A non-field-level 
display file must be specified. Tape label information is 
ignored. 

Records are written to the display with each record 
overlaying the previous record. You can request each 
output record using the Enter key. 


Recognizing Commands That Ignore or Restrict Overrides 


The following commonly used commands ignore overrides entirely: 


ADDLFM DSPJRN 
ADDPFM EDTOBJAUT 
ALCOBJ EDTDLOAUT 
APYJRNCHG ENDJRNPF 
CHGOBJOWN GRTOBJAUT 
CHGPTR INZPFM 
CHGSBSD MOVOBJ 
CHGXXXF (all change file commands) RGZPFM 
CLRPFM RMVJRNCHG 
CLRSAVF RMVM 
CPYIGCTBL RNMOBJ 
CRTIDKTF RSTUSRPRF 
CRTDUPOBJ RVKOBJAUT 
CRTAUTHLR SAVCHGOBJ 
CRTSBSD SAVLIB 
CRTTAPF SAVOBJ 
DLCOBJ SAVPGMPRD 
DLTF SAVSAVFDTA 
DLTAUTHLR SAVSYS 
DSPDBR SBMDBJOB 
DSPFD SIGNOFF 
DSPFFD STRDBRDR 
STRJRNPF 


Overrides are not applied to any system files that are opened as part of an end-of- 
routing step or end-of-job processing. For example, overrides cannot be specified 
for the job log file. In some cases, when you need to override something in a 
system file, you may be able to change it through a command other than an over- 
ride command. For example, to change the output queue for a job log, the output 
queue could be changed before sign-off using the OUTQ parameter on the Change 
Job (CHGJOB) command to specify the name of the output queue for the job. If 
the printer file for the job log contains the value *JOB for the output queue, the 
output queue is the one specified for the job. 


The SRCFILE and SRCMBR parameters on the following commands are affected 
by overrides: overrides for the SRCFILE 


CRTCMD CRTPF 
CRTICFF CRTPRTF 
CRTDSPF CRTSRCPF 
CRTLF CRTTBL 
CRTXXXPGM 


(All create program commands. These commands also use over- 
rides to determine which file will be opened by a compiled program. 
See “Applying Overrides When Compiling a Program” on page 7-4 
for more information.) 


The OPNQRYF command is affected by the following override parameters: 
TOFILE, MBR, SEQONLY, LVLCHK, and INHWRT. 


The following commands allow overrides, but do not allow changing the MBR to 
*ALL: 


CPYFRMPCD CPYTOPCD 
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The following commands do not allow overrides to be applied to the display files 
they use. Overrides to the printer files they use should not change the file type or 
the file name. Various restrictions are placed on changes that may be made to 
printer files used by these commands, but the system cannot guarantee that all 
combinations of possible specifications will produce an acceptable report. 


DMPOBJ and 
DMPSYSOBJ 


DSPXXXXXX 


DSPIGCDCT 
EDTIGCDCT 


GO 
PRTXXXXXX 
QRYDTA 
TROXXX 


WRKXXXXXX 
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(In addition to the preceding limitations, these commands 
do not allow overrides to the file they dump.) 


(All display commands. The display commands 


that display information about a file do not 
allow overrides to that file.) 


(Message file can be overridden.) 


(All print commands.) 


(All trace commands.) 


(All work-with commands.) 


Chapter 8. Handling Messages and Errors for Display Files 


This chapter covers the following: 


¢ Creating and displaying your own messages 
e Analyzing error messages sent from the system 


Creating and Displaying Your Own Messages 


You can create and display your own messages on the AS/400. These messages 
may indicate that a processing error has occurred, that incorrect input has been 
entered, or simply that the keyboard is temporarily locked while the system pro- 


cesses a lengthy request. 


You can specify the following message handling functions for display files: 


¢ Display a message on the message line 


e Display a message on the message line when a subfile control record is written 


¢ Define a message line 


e Display messages in a field on the display 
e Display messages in a program message queue 


Message line 


My menu 


F3=Exit 
Order not found 


Output field 


Ways to show My een 


messages on 


the display Order not found 


F3=Exit 


Subfile 
+Message 1- 
[Message 2] 
(Message 3+ 


You can also do the following: 


ERRMSG and ERRMSGID keywords 


MSGID keyword 


System message support 


RV2W005-2 


e Display error messages on the message line using a system-supplied error 


subfile 


e Have the system automatically handle jobs that are about to receive a perma- 


nent I/O error 


© Copyright IBM Corp. 1997 
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Information about DDS keywords 


This section uses DDS keywords to define and display messages. For more 
information about specific DDS keywords, see the DDS Reference. 


Displaying a Message on the Message Line 
You can specify that a message is to be displayed on the message line with the 
ERRMSG or ERRMSGID keyword. For a message defined as a constant, use the 
ERRMSG keyword; message help is not supported for these kinds of messages. 
For a message defined in a message file, use the ERRMSGID keyword. When you 
use these keywords, the keyboard locks and the user must press the Reset key to 
clear the message from the display and continue. 


When you use ERRMSG, the record that you want to present the message for 
must already be on the display. If it is not, the ERRMSG function is not performed. 


When you use the ERRMSG keyword to present a message, that message is 
written to the message line of the display, which is usually the line at the bottom of 
the screen. The user would then press the Reset key to clear the message from 
the display and unlock the keyboard to continue typing. You provide the text of the 
message right on the ERRMSG keyword. When you write a record that has the 
ERRMSG keyword in effect, it causes that message to appear. Typically, you 
would use an option indicator to cause the ERRMSG keyword to take effect. When 
the application program turns on an option indicator, the keywords that have that 
option indicator specified in the DDS then take effect. In this case, an application 
program would leave an indicator that optioned an ERRMSG keyword off until the 
message needed to be displayed. 


The ERRMSGID and SFLMSGID keywords have an optional parameter for 
message data (msg-data). This allows you to define a program-to-system field that 
contains the message data (substitution text). For more information on how the 
message data parameter works, refer to the Send Program Message CL command 
in the CL Reference. 


Note: When you use the ERRMSG or ERRMSGID keyword, you should specify 
RSTDSP(*YES) on the CRTDSPF or CHGDSPF command; otherwise, data 
may be lost if the display file is suspended. 


Displaying a Message on the Message Line When a Subfile Control 
Record is Written 
You can specify that messages are to be displayed on the message line when a 
subfile control record is written using the SFLMSG or SFLMSGID keyword. If the 
message is a constant, use the SFLMSG keyword; if it is defined in a message file, 
use the SFLMSGID keyword. The restrictions on these keywords are the same as 
ERRMSG and ERRMSGID. 
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Displaying a Message on the Message Line Using a Message Field 
You can specify a message field (M in position 38). The value from this output field 
will appear on the message line. The value in the field is specified by the applica- 
tion program in the output buffer. The length of this field should not exceed 78 
positions if the message is to be displayed on a 24 by 80 screen, or 130 positions if 
the message is to be displayed on a 27 by 132 screen. Message help and substi- 
tution variables are not supported for a message line. 


Priorities for Displaying Messages on a Message Line 
The message displayed on the message line is determined by the following order of 
priority (1 is the highest): 


. ERRMSG 

. ERRMSGID 

. SFLMSG 

. SFLMSGID 

5. Position 38 in DDS is M 


OND — 


In addition, you can change the line on which messages are displayed by using the 
MSGLOC keyword. If not specified otherwise, the message line is the last line on 
the display. If you use the MSGLOC keyword, the new message line applies to 
messages that are displayed for validity-checking errors and keys that are not valid 
as well as to user-defined messages. 


Notes: 


1. If the MSGLOC keyword is not specified, and a display station capable of dis- 
playing 27 lines is attached to a local display station controller or attached to a 
remote 5294 or 5394 controller, the default values are: 


e Line 28 for the 27 by 132 screen size 
e Line 25 for the 24 by 80 screen size 


2. If line 25 is specified for the 24 by 80 mode, either because the default was 
used or line 25 was specified in the MSGLOC keyword, the message actually 
appears on line 24 unless the display is capable of displaying the message on 
line 25. 


3. The normal system display for message help gives the user access to 
extended help (by pressing the Help key again), and may allow the user to use 
F10 to display all messages in the job log. The message help display used for 
a display station other than the job requester display station or for a display 
station associated with a multi-display file does not provide these functions. 


Displaying Messages in a Field on the Display 
You can specify that messages are to be displayed in a field on the display using 
the MSGID keyword. The message is truncated if it is longer than the MSGID field. 
The message is padded with blanks if it is shorter than the MSGID field. 


When the MSGID keyword is used, the keyboard is not locked because the field on 


which it is specified is a normal output-capable field. Message help and substi- 
tution variables are not supported for the MSGID keyword. 
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Displaying Messages on a Program Message Queue 
You can specify that messages that are contained on a program message queue 
are to be displayed by using the SFLMSGRCD, SFLMSGKEY, and SFLPGMQ 
keywords. When you use subfile support for messages, you can display more than 
one message at a time and the keyboard does not lock while the message is being 
displayed. Because the messages specified here are from the program message 
queue, both message help and substitution text are supported. See “Displaying 
Error Messages from Subfiles” on page 4-23 for more information. See also the 
CL Programming book for information on message queues and sending messages. 


Displaying Error Messages through a Subfile 
The ERRSFL (error subfile) keyword can be used to indicate that the error mes- 
sages associated with ERRMSG, ERRMSGID, SFLMSG, and SFLMSGID keywords 
will be displayed on the message line using a system-supplied error subfile. 


The ERRSFL keyword can be used in addition to the ERRMSG and ERRMSGID or 
SFLMSG and SFLMSGID keywords to allow a user to roll through a subfile of error 
messages. One error message is displayed at a time. The user's program handles 
the validity checking of the fields, setting on the option indicators for the appropriate 
message to be sent for the fields in error. The system handles putting the 
message associated with the field in error in the error subfile, and displaying the 
error messages. 


The ERRSFL keyword can also be used to put error messages into an error subfile 
when the system handles validity checking. Error messages are put into the error 
subfile when input fails the validity check for the following reasons: 


¢ DDS keywords CHECK(M10 M11 VN VNE), COMP, RANGE, and VALUES 
e Floating point operations 


¢ More than one decimal point is entered in a field that has one or more decimal 
positions 


e Either too many or too few decimal positions are entered in a field that has one 
or more decimal positions 


The messages can be viewed by paging through the error subfile. Only one error 
message is displayed at a time. When the error subfile is displayed, the keyboard 
is not locked. It is not necessary to press the Reset key prior to correcting the 
fields in error. 


If there is a record format currently displayed that covers the line defined to be the 
message line, the ERRSFL keyword is ignored. 


When both validity checking and ERRMSG/ERRMSGID or SFLMSG/SFLMSGID 
are used on the screen at the same time, the resulting errors are not all present in 
the error subfile at the same time. When the write operation is done, the messages 
from ERRMSG, ERRMSGID, SFLMSG, and SFLMSGID are present in the error 
subfile. After data is typed and validity checking errors occur, the error subfile is 
cleared and only the validity checking errors are present. 


Following is an example of how the ERRSFL keyword can be used: 
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[washes weds cwieteey sve wwt eee des oot awed cape sSe ect a5 Ott eeT ose 


A MSGLOC (24) 

A ERRSFL 

A R RCD1 

A FIELD1 5A B 2 3 

A 10 ERRMSGID(MSGQ001 MSGF1 10 &MDTA1) 
A ll ERRMSG('Error Msg 1' 11) 

A FIELD2 10A B 3 3 

A 20 ERRMSG('Error Msg 2' 20) 

A 21 ERRMSGID(MSGQ002 MSGF1 21) 

A 22 ERRMSGID(MSGOQ03 MSGF1 22 &MDTA3) 
A FIELD3 2A B 4 3 

A 30 ERRMSGID(MSG0004 MSGF1 30) 

A MDTA1 78A P 

A MDTA3 78A P 

A 

A 

A 

A 

A 

A 


Figure 8-1. Sample DDS Source for ERRSFL Keyword 


In this example, assume that RCD1 is currently on the display. When validating the 
input data, your program detects several errors and sets on the option indicators 
11, 21, and 30. On the subsequent output operation: 


e FIELD1, FIELD2, and FIELD3 are displayed in reverse image. 
e The cursor is located in position 2, 3 (start of FIELD1). 
e The keyboard is not locked. 


e An error subfile is displayed on line 24. The subfile contains three records: 
Error Msg 1, the MSG2 message, and the MSG4 message. The user can 
page through the messages, and by placing the cursor on the message line 
and pressing the Help key, view the message help for MSG2 or MSG4. 
Message CPF9897, which indicates that no help information is available, is dis- 
played if the cursor is not located on the message line when the user is 
attempting to view the message help of MSG2 or MSG4. 


e lf the Help key is pressed on the message line for Error Msg 1, the message 
help for message CPF9897 appears. The message help explains that no 
message help is available. 


¢ On the subsequent display of RCD1, the error subfile is cleared of the previous 
error messages. 


The following is a DDS example of defining the SFLMSGID keyword in a display 
file: 
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| cat iisie eee Peep lovee tayo Seds sheen ie eect Svea ies Ovi tea Sales 
MSGLOC (24) 
ERRSFL 
R SFLRCD1 SFL 
SFL1 5A B 2 3 
R CTLRCD1 SFLCTL(SFLRCD1) 
SFLPAG(1) 
SFLSIZ(15) 
SFLDSP SFLDSPCTL 
10 SFLMSGID(SFLOQO01 USERMSGF 10) 
11 SFLMSG('Error Msg 1' 11) 
R SFLRCD2 SFL 
SFL2 7A 0 4 3DFT('FIELD 2') 
R CTLRCD2 SFLCTL(SFLRCD2) 
SFLPAG(1) 
SFLSIZ(15) 
SFLDSP SFLDSPCTL 
20 SFLMSG('Error Msg 2' 20) 
21 SFLMSGID(SFLOO002 USERMSGF 21) 


rFrrrrrrrrrrrrrrrrrr,Tr 


Figure 8-2. Sample DDS Source for SFLMSGID Keyword 


Assume that CTLRCD1 and CTLRCD2 are on the display. When validating the 
input data, your program detects several errors and sets on the option indicators 11 
and 21. On the subsequent output operation: 


e The cursor is located in position 2, 3 (start of SFLRCD1). 
e¢ The keyboard is not locked. 


e An error subfile is displayed on line 24. The subfile contains two records: 
Error Msg 1 and the message of SFLO002. The user can page through the 
messages, and by placing the cursor on the message line and pressing the 
Help key, view the message help for SFLO002. If the Help key is pressed on 
the message line for Error Msg 1, the message help for message CPF9897 
appears, which explains that no help information is available. 


¢ On the subsequent display of CTLRCD1 and CTLRCD2, the error subfile is 
cleared of the previous error messages. 


The SFLEND keyword is specified on the ERRSFL subfile control record. An error 
is issued and the keyboard is locked if the user attempts to roll beyond the top or 
bottom of the file. 


The following considerations apply to the ERRSFL keyword, except when used with 
the ERRMSG and ERRMSGID keywords and the SFLMSG and SFLMSGID 
keywords: 


e When the error subfile is displayed (that is, there are one or more fields in 
error), pressing a Roll key results in the error subfile being rolled, regardless of 
the cursor position at the time or whether other subfiles are currently displayed. 


¢ When processing errors from validity check, the error subfile is built every time 
a valid command key, Roll key, or Enter key is pressed and errors occur. 
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e When a valid command key or Enter key is pressed, the message for the first 
field in error is always displayed. 


e If the error subfile is rolled and the field that corresponds to the message that 
was displayed when the Roll key was pressed is valid, the error subfile is dis- 
played with the message of the first field in error. 


e If the error subfile is rolled and the field that corresponds to the message that 
was displayed when the Roll key was pressed is not valid, the error subfile is 
rolled to the next field in error. 


e¢ When rolling through the error subfile, the cursor is positioned in the field corre- 
sponding to the error message being displayed. 


e If no fields are in error and a Roll key is pressed, a roll is attempted on the 
subfile and a roll error message is displayed (assuming no other area that can 
be rolled is encountered first). See Chapter 4, “Displaying Groups of Records 
Using Subfiles” on page 4-1 for more information about rolling subfiles. 


e If the program writes a record and the user presses a Roll key after typing data 
that is not valid, the error subfile is built and the error message for the first field 
in error is displayed. 


Sounding an Alarm for Messages 


To sound an audible alarm when an active ERRMSG, ERRMSGID, SFLMSG, or 
SFLMSGID keyword is detected or when a validity check message is displayed, 
specify the MSGALARM keyword. This keyword is allowed at the file or record 
level. The alarm sounds for only a short time. 


The MSGALARM keyword can be used on any record in a display file, including 
subfile control records. The MSGALARM keyword can also be used with the 
ERRSFL keyword. 


Note: If the MSGALARM and ALARM keywords are specified and active on the 
same record format, the alarm sounds only once. 


If the SFLMSG or SFLMSGID keyword is active and both the MSGALARM 
and ALARM keywords are specified, an alarm is sounded. If no message is 
displayed, the ALARM keyword and not the MSGALARM keyword is 
responsible for sounding the alarm. 


Automatically Handling Permanent I/O Errors on Display Stations 


Permanent I/O errors on display stations can be handled automatically when you 
use the device-recovery-action job attribute. The Device Recovery Action 
(DEVRCYACN) parameter of the Change Job (CHGJOB) command indicates a 
system action for jobs that are about to receive a permanent I/O error (Such as a 
display station being powered off). You can use the following parameter values: 


*DSCMSG When the I/O error occurs, the system runs a Disconnect Job 
(DSCJOB) command to suspend the job. The user remains dis- 
connected until signing on again to the same display. The job is 
resumed at the point just after the I/O operation. Display data 
management sets the major/minor return code to 83E1 and sends 
a CPF509F message to the program message queue. These indi- 
cate that the display has been cleared and is again available for 
use. 
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*DSCENDRQS _ This option also runs the DSCJOB command when an I/O error 
occurs, but when the job is resumed, the system runs the End 
Request (ENDRQS) command to give control to the most recent 
request-processing program. 


*ENDJOB When an I/O error occurs, the job ends automatically and its priori- 
ties are lowered to conserve system resources. 


*ENDJOBNOLIST Again, the job ends automatically and its priorities are lowered to 
conserve system resources. However, no job log is produced for 
the job. 


When an I/O error occurs (especially in the case of a communications line failing 
for several active jobs at once), using the device-recovery-action job attribute can 
save system resources. Also, the device-recovery-action job attribute makes the 
job of coding for I/O errors easier. Once the display station is recovered, the user 
application can continue at the point the error occurred by using the *~DSCMSG and 
“DSCENDRQS values. For *DSCMSG, if the major/minor return code is 83E1 after 
an I/O operation, the program needs to assume that the display is blank. The 
program must branch back to the point at which the first I/O operation to the display 
is done. For *DSCENDRQS, the request-processing program receives control 
when connecting to the job again. This is similar to selecting option 2 on the 
System Request menu. No error recovery is performed for *MSG or *DSCMSG 
until an I/O operation is performed to the device in error. For all other values, the 
recovery occurs immediately when the error occurs. 


The device-recovery-action job attribute works only for *REQUESTER display 
stations and does not apply to batch jobs, pass-through jobs, or work-station- 
function jobs. 


Analyzing Error Messages Sent from the System 


This section describes error conditions that an application program may encounter 
during its operation and the provisions that can be made within the program itself to 
attempt to deal with these conditions. The CL Programming book discusses how to 
use the debug functions to resolve unexpected errors encountered in the applica- 
tion programs. The chapter on handling problems in the Basic System Operation, 
Administration, and Problem Handling book describes the programs that are avail- 
able for analyzing and reporting system errors and hardware failures. 


Errors can be detected when a file is opened, when a program device is acquired 
or released, during I/O operations to a file, and when the file is closed. When 
appropriate, the system will automatically try to run a failing operation again, up to 
a retry limit. When a retry is successful, neither operator nor program action is 
required. Errors that can affect the processing of the program may be reported in 
any or all of the following ways: 


¢ A notify, status, diagnostic, or escape message may be sent to the program 
message queue of the program using the file. These messages may also 
appear in the job log, depending on the message logging level set for the job. 


¢ A notify, status, diagnostic, or escape message may be sent to the operator 
message queue (QSYSOPR) or the history message queue (QHST). 


e A file status code may be returned by the high-level language. 


e A major/minor return code is returned in the I/O feedback area for display files. 
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Understanding 


¢ Information regarding the error may be saved in the system error log for use by 
the problem analysis and resolution programs. 


e An alert message may be sent to an operator at another system in the network. 


e¢ The normal program flow may be interrupted and control may be transferred to 
an error-handling subroutine, or other language operations may occur. For 
additional information about how to handle run-time errors, see the appropriate 
high-level language manual. 


Only some of these are significant to a program that is attempting error recovery. 


Not all file errors allow programmed error recovery. Some errors are considered 
permanent; that is, the file, device, or program cannot work until some corrective 
action is taken. This might involve resetting the device by varying it off and on 
again, or correcting an error in the device configuration or the application program. 
Some messages and return codes are used to inform the user or the application 
program of conditions that are information rather than errors, such as change in the 
status of a communications line, or system action taken for an unexpected condi- 
tion. In many cases, it is possible for the application program to test for an error 
condition and take some preplanned recovery action which allows the program to 
continue without intervention from the user. 


Messages and Message Monitors 


Displayed messages are the primary source of information for anyone who is 
testing a new application. A message usually contains more specific information 
than the file status code, the indicators, or the major/minor return code. The control 
language allows messages to be monitored so that the CL program can intercept a 
message and take corrective action. See the CL Programming book for more infor- 
mation about message types and message monitors. In most high-level languages, 
either the file status code or major/minor return code (described in the following 
section) is a more convenient source of information. 


Message numbers are assigned in categories to make it easier for a program to 


monitor for any of a group of related messages. The following message number 
ranges are assigned for file error messages: 
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Table 8-1. System Message Number Ranges 


Message IDs Operation Message Type 

CPF4001—40FF Open Diagnostic and status. 

CPF4101—43FF Open Escapes that make the file unusable. 

CPF4401—44FF Close Diagnostic and status. 

CPF4501—46FF Close Escapes that make the file unusable. 

CPF4701—48FF I/O, Acquire, and Notify with a default reply of cancel, status and 
Release escapes that do not make the file or device 

unusable. 

CPF4901—49FF I/O, Acquire, and Notify with a default reply of ignore. 
Release 

CPF5001—50FF I/O, Acquire, and Notify with a default reply of cancel. 
Release 

CPF5101—53FF I/O, Acquire, and Escapes that make the file or device unusable. 
Release 

CPF5501—56FF I/O, Acquire, and Escapes that make the file or device unusable. 
Release 


Some status messages, CPF4018 for example, are preceded by a diagnostic 
message that provides additional information. Diagnostic messages may be kept in 
the job log, depending on the message logging level of the job. If a CL program 
monitors for CPF4018, CPF5041, or similar messages, it can retrieve the accompa- 
nying diagnostic message from the program message queue. 


If an error occurs for which an escape message is issued and the message is not 
monitored, your program will be ended and the message displayed in the operator 
message queue. Status messages may also be monitored, but if they are not mon- 
itored, the program continues. Most high-level languages except CL monitor for all 
the file errors that are likely to be encountered, and provide some standard 
recovery. Depending on the severity of the error, the high-level language may 
simply end the program and issue a message of its own. Alternatively, you may 
code an error recovery routine to handle errors that are anticipated in that particular 
application. 


Within these error-handling routines, it is usually necessary to examine the file 
status or major/minor return codes to determine the cause of the error. The 
manuals for the language you are using explain how to access file status and 
major/minor return codes. The language manuals also explain the file status codes 
as they are defined for each language. 


Understanding Major/Minor Return Codes 


Major/minor return codes are used to report errors and certain status information for 
display files. They are usually stated as four characters: the first two referring to 
the major code and the second two referring to the minor code. The major code 
indicates the general type of error, and the minor provides further detail. Minor 
codes, except zero, have the same or a similar meaning, regardless of the major 
code with which they are combined. 


The application program can test the return code after each I/O operation. If the 
major return code is 00, the operation completed successfully and the minor return 
code contains status information that indicates whether a read or a write operation 
should be performed next. A major return code of 04 or above indicates that an 
error occurred. The program may test for any specific errors for which programmed 
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recovery is attempted. The application program may test for a specific condition by 
comparing the major and minor codes as a unit, or may identify a class of condi- 
tions by testing the major code alone. 


Most major/minor return codes are accompanied by any one of several message 
numbers, for which the typical recovery action is similar. File status codes are 
defined by the individual languages and may be set based on the major/minor 
return codes. 


The following table defines the major return codes. Appendix E, “Display File 
Return Codes” contains specific definitions of the major and minor return codes as 
they are used for display files and the message numbers associated with each. 


Table 8-2. Major Return Code Definitions 


Code Definition 

00 The operation requested by your program completed successfully. The minor 
includes state information, such as change direction. 

02 Input operation completed successfully, but job is being ended (controlled). The 
minor includes state information. 

03 Successful input operation, but no data was received. The minor includes state 
information. 

04 Error occurred because an output operation was attempted while data was 
waiting to be read. 

08 An acquire operation failed because the device has already been acquired or the 
session has already been established. 

11 A read-from-invited-program-devices operation failed because no device or 
session was invited. 

34 An input exception occurred. The data length or record format was not accept- 
able for the program. 

80 A permanent system or file error, which cannot be recovered from, occurred. 
Programmer action is required to correct the problem. 

81 A permanent device or session error, which cannot be recovered from, occurred 
during an I/O operation. 

82 A device or session error occurred during an open or acquire operation. 
Recovery may be possible. 

83 A device or session error occurred during an I/O operation. Recovery may be 
possible. 


Recovering from Errors 


The following sections describe the error recovery action that is appropriate for 
each group of major return codes. 


Normal Completion 

A major/minor return code of 0000 indicates that the operation requested by your 
program was completed successfully. Most of the time, no message is issued. In 
some cases, a diagnostic message might be used to inform the user of some 
unusual condition that the system was able to handle, but which might be consid- 
ered an error under some conditions. For example, a parameter that is not valid 
might be ignored, or some default action taken. 
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Completion with Exceptions 
Several rather specific major return codes have been assigned to conditions for 
which a specific response from the application program is appropriate. 


A major return code of 02 indicates that the requested input operation completed 
successfully, but the job is being ended (controlled). The application program 
should complete its processing as quickly as possible. The controlled cancel is 
intended to allow programs time to end in an orderly manner. If your program does 
not end within the time specified on the ENDJOB command, the job will be ended 
by the system without further notice. 


A major return code of 03 indicates that an input operation completed successfully 
without transferring any data. For some applications, this might be an error condi- 
tion, or it might be expected when the user presses a function key instead of 
entering data. It might also indicate that all the data has been processed, and the 
application program should proceed with its completion processing. In any case, 
the contents of the input buffer in the program should be ignored. 


A major/minor code of 0309 is used to indicate that no data was received and the 
job is being ended (controlled). A major/minor code of 0310 indicates that there is 
no data because the specified wait time has ended. Other minor return codes 
accompanying the 02 or 03 major code are the same as for a 00 major code, indi- 
cating communications status and the operation to be performed next. 


A major return code of 04 indicates that an output exception occurred. Specifically, 
your program attempted to send data when there was data waiting to be received. 
This is probably the result of not handling the minor return code properly on the 
previous successful completion. Your program can recover by simply receiving the 
incoming data and then repeating the write operation. 


A major return code of 34 indicates that an input exception occurred. The received 
data was either too long or incompatible with the record format. The minor return 
code indicates what was wrong with the received data, and whether the data was 
truncated or rejected. Your program can probably handle the exception and con- 
tinue. If the data was rejected, you may be able to read it by specifying a different 
record format. 


Two other return codes in this group, 0800 and 1100, are both usually the result of 
application programming errors, but are still recoverable. 0800 indicates that an 
acquire operation failed because the device has already been acquired or the 
session has already been established. 1100 indicates that the program attempted 
to read from invited devices with no devices invited. In both cases, the request that 
is not valid is ignored, and the program may continue. 


No message is issued with a 02 major code or most minor codes with the 03 major 


code, but the other exceptions in this group are usually accompanied by a message 
in the CPF4701—CPF47FF or CPF5001—CPF50FF range. 
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Permanent System or File Error 

A major return code of 80 indicates a serious error affecting the file. The applica- 
tion program must close the file and reopen it before attempting to use it again, but 
recovery is unlikely until the problem causing the error is found and corrected. To 
reset an error condition in a shared file by closing it and opening it again, all pro- 
grams sharing the open data path must close the file. This may require returning to 
previous programs in the program stack and closing the shared file in each of those 
programs. You should refer to the text of the accompanying message to determine 
what action is appropriate for the particular error. 


Within this group, several minor return codes are of particular interest. A 
major/minor code of 8081 indicates a serious system error for which an APAR 
probably will be required. The message sent with the major/minor return code may 
direct you to run the Analyze Problem (ANZPRB) command to obtain more informa- 
tion. 


A major/minor code of 80EB indicates that incompatible options or options that are 
not valid were specified in the display file or as parameters on the open operation. 
In most cases you can close the file, end the program, correct the parameter that is 
not valid with an override command, and run the program again. The override 
command affects only the job in which it is issued. It allows you to test the change 
easily, but you may eventually want to change or re-create the display file as 
appropriate to make the change permanent. 


Permanent Device or Session Error on I/O Operation 

A major return code of 81 indicates a serious error affecting the device or session. 
This includes hardware failures affecting the device, communications line, or com- 
munications controller. It also includes errors due to a device being disconnected 
or powered off unexpectedly and abnormal conditions that were discovered by the 
device and reported back to the system. Both the minor return code and the 
accompanying message provide more specific information regarding the cause of 
the problem. 


Depending on the file type, the program must either close the file and open it again, 
release the device and acquire it again, or acquire the session again. To reset an 
error condition in a shared file by closing it and opening it again, all programs 
sharing the open data path must close the file. In some cases, the message may 
instruct you to reset the device by varying it off and on again. It is unlikely that the 
program will be able to use the failing device until the problem causing the error is 
found and corrected, but recovery within the program may be possible if an alter- 
nate device is available. 


Some of the minor return codes in this group are the same as those for the 82 
major return code. Device or line failures may occur at any time, but an 81 major 
code occurs on an I/O operation. This means that your program had already 
established a link with the device or session. Therefore, some data may have been 
transferred, but when the program is started again, it starts from the beginning. A 
possible duplication of data could result. 


Message numbers accompanying an 81 major code may be in the range indicating 
either an I/O or a close operation. A device failure on a close operation simply may 
be the result of a failure in sending the final block of data, rather than action spe- 
cific to closing the file. An error on a close operation may result in the file being left 
partially closed. Your error recovery program should respond to close failures with 
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a second close operation. The second close will always complete, regardless of 
errors. 


Device or Session Error on Open or Acquire Operation 

A major return code of 82 indicates that a device or session error occurred during 
an open or acquire operation. Both the minor return code and the accompanying 
message will provide more specific information regarding the cause of the problem. 


Some of the minor return codes in this group are the same as those for the 81 
major return code. Device or line failures may occur at any time, but an 82 major 
code indicates that the device or session was unusable when your program first 
attempted to use it. Thus no data was transferred. The problem may be the result 
of a configuration or installation error. 


Depending on the minor return code, it may be appropriate for your program to 
recover from the error and try the failing operation again after some waiting period. 
The number of times you try should be specified in your program. It may also be 
possible to use an alternate or backup device or session instead. 


Message numbers accompanying an 82 major code may be in the range indicating 
either an open or an acquire operation. If the operation was an open, it is neces- 
sary to close the partially opened file and reopen it to recover from the error. If the 
operation was an acquire, it may be necessary to do a release operation before 
trying the acquire again. In either case, the file wait time should be specified long 
enough to allow the system to recover from the error. 


Recoverable Device or Session Errors on I/O Operation 

A major return code of 83 indicates that an error occurred in sending data to a 
device or receiving data from the device. Recovery by the application program is 
possible. Both the minor return code and the accompanying message provide 
more specific information regarding the cause of the problem. 


Most of the errors in this group are the result of sending commands or data that are 
not valid to the device, or sending valid data at the wrong time or to a device that is 
not able to handle it. The application program may recover by skipping the failing 
operation or data item and going on to the next one, or by substituting an appro- 
priate default. There may be a logic error in the application. 
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Chapter 9. Creating and Accessing Menus Using Display 
Files 


This chapter describes user-defined menus and tells you how to create them and 
use them with system menus. 


The first two types of user-defined menus can be created using the information in 
this chapter: 


Display file menus Menus that use a display defined by data description specifi- 
cations (DDS) to present a menu format. The menu func- 
tions are controlled by a message file containing the 
commands used to run each of the menu options. 


Program menus Menus that use a high-level language program to present the 
menu format and provide the functions necessary to run the 
menu options. 


UIM menus Menus that a menu object defined by the user interface 
manager (UIM) panel group definition language. For more 
information on defining your own menus using the UIM, see 
“Defining a Menu Object Using UIM” on page 16-6. 


-—— Information about CL commands 


Some of the examples in this chapter use CL commands. For more information 
about specific CL commands, see the CL Reference. 


Running System and User-Defined Menus 


Menus that consist of *MENU object types are run using the Go to Menu (GO) 
command. The GO command allows you to specify either a particular menu or a 
generic menu name. If you specify a generic name, you are shown the Work with 
Menus display, which shows all the menus available for your use. From this list, 
you can choose a menu to run. 


Returning to a Menu after Running the GO command 


Using the Return Point (RTNPNT) parameter of the GO command, you can specify 
whether or not you want to return to the menu from which the command was 
entered after running the menu specified by the GO command. 


Determining the Previous Menu 


A menu is placed on an internal menu stack before it is run. If a stack is not avail- 
able for the menu, one is created. When the Cancel key is pressed for a menu, 
the previous menu in the stack is shown. Each menu stack is 10 elements 
(menus) deep. When the eleventh menu is placed on the menu stack, the first, or 
oldest, menu is removed from the stack. This menu cannot be returned to by using 
the Cancel key. 
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Using the Cancel and Exit Keys on Menus 


In the following example, a series of menus is presented using both the menu 
options and the GO command. 


1. From the AS/400 Main Menu, GO PROGRAM RTNPNT(*YES) is typed on the 
command line. Specifying RTNPNT(*YES) here means that the Main Menu will 
be used as a return point. 


Main Menu 


System 


XXXXXXXX 


one of the following: 


User tasks 

Office tasks 

General system tasks 

Files, libraries, and folders 
Programming 

Communications 

Define or change the system 
Problem handling 


WOONDOAHBPWNHE 


wo 
fo) 


Display a menu 


Sign off 


Selection or Command 
===> GO PROGRAM RTNPNT(*YES) 


F3=Exit F4=Prompt 
F23=Set initial menu 


F9=Retrieve F12=Cancel F13=Information Assistant 


— — 


2. Next, by typing GO PROBLEM RTNPNT(*NO) on the command line of the Program- 
ming menu and pressing the Enter key, the Problem Handling menu is shown. 
The Programming menu is not set as a return point. 


— 


PROGRAM 


Select 


OnNaAnPWNE-E 


ao 
fo) 


70. 


Programming 


one of the following: 


Programmer's menu 


Programming Development Manager 


Utilities 

Programming language debug 
SQL pre-compiler 

Question and answer 

IBM product information 
Copy screen image 


. System/36 programming 


Related commands 


System — XXXXXXXX 


Selection or Command 
===> GQ PROBLEM RTNPNT(*NO) 


F3=Exit F4=Prompt 
Fl6=System main menu 


F9=Retrieve F12=Cancel F13=Information Assistant 
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— aa 


PROBLEM Problem Handling 
System = XXXXXXXX 
Select one of the following: 


- Question and answer 

. Work with problems 

. Network problem handling 

. Display system operator messages 
. Display the history log 

. System service tools 


AomnrwNnr 


60. More problem handling options 


70. Related commands 


Selection or Command 
===> 


F3=Exit F4=Prompt F9=Retrieve  F12=Cancel F13=Information Assistant 
Fl6=System main menu 


— — 


3. In this example, if the Cancel key is pressed while viewing the Problem Han- 
dling menu, the user is returned to the Programming menu because the Pro- 
gramming menu is the preceding display on the menu stack. If F3 (Exit) is 
pressed while viewing the Problem Handling menu, the user is returned to the 
Main Menu, because the Main Menu is the most recent display from which a 
GO command was entered with RTNPNT(*YES). 


Note that since the default value for the RTNPNT parameter is “YES, GO PROBLEM 
will have the same effect as GO PROBLEM RTNPNT(*YES). 


Pressing either F3 (Exit) or F12 (Cancel) while viewing the help for a menu returns 
the user to the menu itself. 


Choosing the Menu That Is Shown at Sign-On Time 


To specify a menu as your initial menu, or the first menu you see when you sign 
on, press F23 when the menu is shown. F23 sets the initial menu attribute in your 
user profile. Unless your initial program requests some other menu, the menu 
selected by pressing F23 is shown as the initial menu the next time you sign on. 


Note: You can only use this key if LMTCPB(*NO), which allows you to change the 
initial menu, is specified in your user profile. 


See the Security — Reference for information about initial menus and limited users. 
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Defining Your Own Display File Menus 


Display file menus consist of three parts: 


e¢ A DDS-defined display file to define the way the menu looks at the display 


station 


¢ A message file to define what action is taken when any of the menu options 


are selected 


¢ A menu object (*MENU) that contains the menu 


Help is available on display file menus for the following: 


Commands Command help is shown by typing the command on the 
command line, then pressing the Help key. 

Function keys — Help for function keys is shown by moving the cursor to the func- 
tion area and pressing the Help key. 

Messages Help for messages is shown by moving the cursor to a message 
and pressing the Help key. 


Help for the menu options may also be provided using DDS. See “Naming Help 
Formats for Menus” on page 9-6 for more about help information. 


;—— Information about DDS keywords 


More information about the specific DDS keywords used in this chapter is found 
in the DDS Reference. 


Understanding DDS and Display File Considerations for Menus 
Several restrictions exist for the DDS used in defining a menu: 


Table 9-1 (Page 1 of 2). Restrictions for Display File Menus 


Affected Area 


Restriction 


Display size 


The menu format and the associated help record formats for the 
menu in the display file must have a display size of 24 rows by 80 
columns, DSPSIZ(*DS3) in DDS. 


Display file and 
record format names 


The menu record format name must be the same as the display file 
name. 


Help format names 


Help format names must follow the convention #Hxxyy, described in 
“Naming Help Formats for Menus” on page 9-6. The help record 
format is limited to 150 items. 


Indicator area 


A separate indicator area (INDARA keyword) must be declared in 
the DDS for the display. 


Subfile use 


Subfiles cannot be used. 
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Table 9-1 (Page 2 of 2). Restrictions for Display File Menus 


Affected Area 


Restriction 


Allowed lines 


Only the first 21 lines of the display should be described. Only the 
first 21 lines of the help display should be described. Lines 22 and 
23 are used with long command lines; system messages are 
shown on line 24. (Line 23 is used with short command lines and 
line 24 is used for messages.) 


The following lines can be used when a function key legend is 
requested: 


e For along command line with no function key legend, lines 1 
through 21 

e For along command line with a function key legend, lines 1 
through 19 

e For a short command line with no function key legend, lines 1 
through 22 

e For a short command line with a function key legend, lines 1 
through 20 

e For no command line with no function key legend, lines 1 
through 21 

¢ For no command line with a function key legend, lines 1 
through 19 


Keyboard locking 


The LOCK record level keyword should be used to prevent the key- 
board from unlocking before the display is shown. 


Paging 


The Allow Roll (ALWROL) record level keyword cannot be speci- 
fied. 


Deferring the write 
operation 


DFRWRT(*NO) is required on the CRTDSPF command when cre- 
ating a display file menu. DFRWRT(*NO) ensures the menu format 
is displayed when the menu is run. 


The following suggestions can also be used to help you define your menu using 


DDS: 


Table 9-2. Suggestions for Display File Menus 


Affected Area 


Option 


Restoring the display 


The RSTDSP(*NO) is optional on the CRTDSPF command, but 
may significantly improve system performance if specified. 


Menu and display 
station alias 


An alias can be used for the name of the menu and for the name 
of the display station (for the System/36 environment). When 
issuing the CRTMNU command, you can specify a different name 
than the name used in the DDS. This way, the name of the display 
station identifier will be displayed with the menu. By giving the 
menu a different name, you can use the GO command to find that 
menu. 


Describing Menu Actions in a Message File 


Message files are used to describe what action is taken when a menu option is 
selected. Commands controlling the action to be taken are usually placed in the 
message. In some cases, the command string may be too long to fit in the 
message. In these cases, the message contains the message identifier for the 
message; the command is then placed in the message help. 
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Messages used in display file menus must be named using the message prefix 
USR. The remaining four digits of the message identifier correspond to the menu 
option number. 


For example, if option 3 on a given display file menu is: 
3. Personnel Menu 


then the message describing the action taken when 3 is entered on the command 
line uses identifier USROO03. The message could contain any command, such as 
'GO PERSMENU RTNPNT(«NO) '. 


See “Creating and Displaying Your Own Messages” on page 8-1 for more informa- 
tion about messages. 


Naming Help Formats for Menus 
Help formats for display file menus are named using the form: 


#Hxxyy 
where: 


xx is the number of the first menu option to which the help information applies 
yy is the number of the last menu option to which the help information applies 


For example, #H0103 could be used to name help that applies to menu options 1 
through 3. #H0202 names the help that applies to menu option 2. 


#HO000 names the extended help for the menu. 


The help formats may be described in any order in the DDS. The system sorts the 
help formats in ascending order when the menu is run. 


If two or more help format names apply to the same option, only the first help 
format (as sorted by the system) will be shown when Help is requested for that 
option. For example, if the following help formats are given: 


#H0000 
#H0101 
#HO205 
#H0306 
#HO707 


Typing 3 on the command line (to select option 3) and pressing the Help key will 
show the help designated #H0205. In this example, #H0306 can be viewed using the 
Page Down key, but will be shown directly only by requesting help for option 6. 


Similarly, by moving the cursor to the command line and pressing the Help key with 
no option typed on the command line, the user is shown extended help for the 
menu (#H0000). The cursor movement keys can be used to look through the other 
help formats for the menu options. 


The following example shows a menu with five options. The names of the help 


formats and the menu options to which they apply are shown following the 
example. 
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(— _\ 


PERSMENU Personnel Menu 
Select one of the following: 


1. Departments menu 
2. Education menu 
3. Benefits menu 

4. Job openings 

5. Job applicants 


Selection or Command 
===> 


— — 


Help Name Contents 

#HO0000 General help for the Personnel Menu (PERSMENU) 

#H0101 Help for option 1, Departments menu 

#H0202 Help for option 2, Education menu 

#H0303 Help for option 3, Benefits menu 

#H0405 Help for options 4 and 5, Job openings and Job applicants 


The help information for the menu options can be shown by typing the option 
number on the command line and pressing the Help key, or by pressing Help 
(extended help for the menu), and then using the Page Down key to page through 
the help for the options. 


Building a Display File Menu 
The following steps allow you to create a display file (“DSPF) menu: 


. Describing the menu and menu help information 
. Creating the display file 

. Creating the message file 

. Adding messages to the message file 

. Creating the menu 

. Running the menu 


oahWND — 


The following sections explain each step in detail. 


Describing the Menu and Menu Help Information 
DDS is used to describe both the appearance and the help for the menu. 


The following DDS is for the sample display called PERSMENU. The first record 
format (PERSMENU) is used to describe the appearance of the menu when dis- 
played. Five menu options are listed, starting in position 7 of lines 5 through 9. 


Five more record formats are shown: #HO000, #HO101, #HO202, #H0303, and 
#H0405. Each of these is used to provide help information for the menu and its 
options. Following the system convention described above (see “Naming Help 
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Formats for Menus” on page 9-6), #H0000 is used to provide extended help for the 
menu. The other record formats provide help for the menu options. 


| vets von leciye Hees olen geiees diva cbs otdecestevesSvaas tenes Oceas teed coe 
Ax PERSONNEL MENU (PERSMENU) SPECIFICATION 
Ax 
A PRINT DSPSIZ(*DS3) 

INDARA 


> 


* 


R PERSMENU LOCK 

Q2' PERSMENU' 

29' PERSONNEL MENU' 

@2'SELECT ONE OF THE FOLLOWING: ' 
Q7'1. DEPARTMENTS MENU' 

Q7'2. EDUCATION MENU’ 

07'3. BENEFITS MENU' 

07'4. JOB OPENINGS' 

07'5. JOB APPLICANTS’ 
O2'SELECTION OR COMMAND' 


FP WOON DOWRY re 


ine) 


* 


R #HOQ00 LOCK 

02'GENERAL' 

26'HELP FOR THE PERSONNEL MENU 
O2'THIS IS THE GENERAL HELP' 


wn r 


w 


27'FOR THE PERSONNEL MENU. ' 


* 


R #H0101 LOCK 

02'HELP1' 

26'HELP FOR OPTION 1' 
O2'THIS IS THE HELP' 
19'FOR OPTION 1.' 


WWrR Fr 


* 


R #HO202 LOCK 

02'HELP2' 

26'HELP FOR OPTION 2' 
O2'THIS IS THE HELP' 
19'FOR OPTION 2.' 


WWrR Fe 


* 


R #H0303 LOCK 

02'HELP3' 

26'HELP FOR OPTION 3' 
O2'THIS IS THE HELP' 
19'FOR OPTION 3.' 


WwWr Fr 


* 


R #HO0405 LOCK 

02'HELP45' 

26'HELP FOR OPTIONS 4 AND 5! 
O2'THIS IS THE HELP' 

19'FOR OPTIONS 4 AND 5.' 


rPrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr}S 
WWrR Fe 


* 


Figure 9-1. DDS Source for Sample Menu Called PERSMENU 
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Creating the Display File 


To create the display file for the menu, enter the following command: 


CRTDSPF FILE(PERLIB/PERSMENU) + 
SRCFILE(USERLIB/SFPERS) + 
DFRWRT(*NO) + 
RSTDSP(*NO) 


The DDS source member, PERSMENU, in the source file SFPERS in library 
PERLIB, is used to create the display file for the PERSMENU menu. 


Creating the Message File 
Enter the following Create Message File (CRTMSGF) command to create a 
message file called PERSMENU (same name as record format): 


CRTMSGF MSGF(PERLIB/PERSMENU) + 
TEXT('Message file of commands for menu PERSMENU. ') 


The message file will be used to contain messages describing the actions taken 
when the various menu options are selected. 


Adding Messages to the Message File 

The Add Message Description (ADDMSGD) command is used to add messages to 
the message file. The messages describe the different actions taken when various 
menu options are selected. 


The MSGID parameter of each ADDMSGD command is in the form USRxxxx, where 
Xxxx is the menu option number. The MSG parameter contains the command to 
run the menu option. 


In the following example, the MSG parameters of the first three messages contain 
commands to run menus (using the GO commana); the last two messages contain 
commands which will call programs (using the CALL command) when either of 
those menu options are selected from the menu. 


ADDMSGD MSGID(USROOO1) MSGF(PERLIB/PERSMENU) + 
MSG('GO DEPTMENU RTNPNT(*NO) ') 
ADDMSGD MSGID(USROOO2) MSGF(PERLIB/PERSMENU) + 
MSG('GO EDUCMENU RTNPNT(*NO) ') 
ADDMSGD MSGID(USROOO3) MSGF(PERLIB/PERSMENU) + 
MSG('GO BENEMENU RTNPNT(*NO) ') 
ADDMSGD MSGID(USROO04) MSGF(PERLIB/PERSMENU) + 
MSG('CALL JOBOPEN') 
ADDMSGD MSGID(USROOO5) MSGF(PERLIB/PERSMENU) + 
MSG('CALL JOBAPPS') 


Creating the Menu Object 
Enter the following Create Menu (CRTMNU) command to create the menu object: 
CRTMNU MENU(PERLIB/PERSMENU) TYPE(*DSPF) DSPF(*MENU) + 


MSGF(*MENU) DSPKEY(*NO) CMDLIN(*LONG) + 
TEXT('Personnel menu') 


The DSPKEY parameter specifies whether the function key legend is shown at the 
bottom of the menu when the menu is displayed. *NO specifies that the function 
key legend is not shown at the bottom of the menu. *YES specifies that the func- 
tion key legend is shown at the bottom of the menu. You do not have the option to 
display only certain function keys. 
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The CMDLIN parameter specifies the length of the command line to be displayed. 
“LONG specifies a 153-byte long command line. “SHORT specifies a 73-byte long 
command line. *NONE specifies a 4-byte option line in place of a command line. 


Note: Note that for both the DSPF and MSGF parameters, the value *MENU was 
specified. *MENU specifies that the name of the display or message file is 
the same as the name of the menu. Display and message file names do 
not have to have the same name as the menu. 


Running the Menu 
The new display file menu can now be run using the GO command: 


GO PERSMENU 


PERSMENU Personnel Menu 
Select one of the following: 


. Departments menu 
. Education menu 

. Benefits menu 

. Job openings 

. Job applicants 


oa rwnrr 


Selection or Command 
===> 


Defining Your Own Program Menus 


Program menus provide an alternative to display file and system menus by using 
the GO command to call a program. The user has complete control of the display 
and function of the program menu through the program. 


Passing Parameters for Program Menus 
Three parameters are passed to the program when the menu is run: 


e The 10-character name of the menu object 
e The 10-character name of the library containing the menu object 
e A 2-character binary return code 


All three parameters must be declared as variables in the program. The return 
code determines how the program menu is exited, simulating the function keys 
found on IBM-supplied menus. The four possible values are: 


Binary Return Hex 
Code Equivalent Description 
0 0000 Call the program (display the menu) again 
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Binary Return Hex 


Code Equivalent Description 
-1 FFFF Exit function requested 
-2 FFFE Previous function requested 
-4 FFFC Home function requested (display the initial menu) 


Note: The hexadecimal values shown above are used for those high-level lan- 
guages (such as CL) that do not support binary numbers. CL programs 
should use a 2-byte character variable. 


Building a Program Menu 


This example shows how a program (*PGM) menu is created. The following steps 
will be shown and described in detail: 


1. Describing the menu 

. Creating the display file 

. Entering source and creating a CL program to control the menu function 
. Creating the menu 

. Running the menu 


oR OW P 


Describing the Menu 

The program menu is designed using data description specifications (DDS) to 
describe the menu's appearance. The following DDS is for the sample display 
called PGMMENU. 


lve tedvedcwePidss2ieeg hice sdeeesteess4veys tee yabcoywhess sO cose tes val eee 
DSPSIZ(*DS3) 
PRINT 
CA03(01) 
CA12(02) 
HOME (03) 
INDARA 
R MENUFMT BLINK OVERLAY 
DSPMNUN 10A 0 1 2 
72 TIME 
31'EXAMPLE PROGRAM MENU' 
DSPATR(HI) 
2'SELECT ONE OF THE FOLLOWING:' 
5'1.' DSPATR(HI) 
10'DISPLAY LIBRARY LIST (DSPLIBL)' 
5'2.' DSPATR(HI) 
10'WORK WITH ACTIVE JOBS (WRKACTJOB) ' 
5'3.' DSPATR(HI) 
10'WORK WITH YOUR JOB — (WRKJOB) ' 
5'90.' DSPATR(HI) 
10'RETURN' 
2'OPTION: ' 
OPTION 3 I 23 12DSPATR(PC) 


a 


rPrrrrrrrrrrrrrrrrrrrrsy 
Do 
WADMNO HLH HB W W PS 


Figure 9-2. DDS Source for Program Menu Example 
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Creating the Display File 
Create the display file using the Create Display File (CRTDSPF) command: 


CRTDSPF FILE(QGPL/PGMDDS) SRCFILE(USERLIB/SOURCE1) 


The DDS source file called SOURCE1 is used to create the display file for the 
PGMMENU menu. 


Entering the Source and Creating a CL Program 
The following CL program is used to control the menu function. (See the CL Pro- 
gramming book for more information about entering CL source.) Note that any 
high-level language supported by the system could be used to control a menu. 
PGM PARM(&MENUNAME &MENULIB &ACTION) /* Begin the program and + 
indicate that 3 parameters will be passed to it when + 
called. The parameters include 1) The menu name, 2) + 


The menu library name 3) The action desired by this + 
program on return. */ 


DCL VAR(&MENUNAME) TYPE(*CHAR) LEN(10) /* Menu name */ 

DCL VAR(&MENULIB) TYPE(*CHAR) LEN(10) /* Menu library name */ 

DCL VAR(&ACTION) TYPE(*CHAR) LEN(2) /* Action variable */ 

DCLF FILE(QGPL/PGMDDS) RCDFMT(MENUFMT) /* Display file «/ 

CHGVAR VAR(&DSPMNUN) VALUE(&MENUNAME) /* Set the menu name on the + 
menu x/ 


SNDRCVF DEV(*FILE) RCDFMT(MENUFMT) /* Display the menu at the + 
display station */ 

CHGVAR VAR(&ACTION) VALUE(X'0000') /* Indicate the menu should + 
be displayed again */ 


[RR RR RRR RAK RRA KKK KK ERA K KIRKE KK KER IKKE AK KEKE RIKKI KER AKER KKK | 


/* Handle function keys x/ 
[RR KR AKER IKKE AK KERR ERIK KAR KEKE KERIKERI KKK KER AK KEA KER AKER ARK | 
IF COND(&INO1 *EQ '1') THEN(CHGVAR VAR(&ACTION) + 
VALUE(X'FFFF')) /* If F3 was pressed, set action + 
to EXIT */ 
IF COND(&INO2 *EQ '1') THEN(CHGVAR VAR(&ACTION) + 


VALUE(X'FFFE')) /* If F12 was pressed, set action + 
to PREVIOUS «/ 


IF COND(&INO3 *EQ '1') THEN(CHGVAR VAR(&ACTION) + 
VALUE(X'FFFC')) /* If HOME was pressed, set action + 
to HOME */ 
[RRRR AKER AK RRA KKK KK ERIK KA K KEIRA KK AK KEIRA KER AKKE KA KER ERK | 
/* Handle menu options */ 
[RR RR AKER A KR AK REAR K EAR KARE KKK ERA K KEK KK EAA A AKER AKER KKK | 
IF COND(&OPTION *EQ '1') THEN(DSPLIBL) /* If the menu user + 
has selected option 1, then display the library list */ 
IF COND(&OPTION *EQ '2') THEN(WRKACTJOB) /* If the menu user + 
has selected option 2, then display the active jobs */ 
IF COND(&OPTION *EQ '3') THEN(WRKJOB) /* If the menu user + 
has selected option 3, then display the current job. */ 
IF COND(&OPTION *EQ '90') THEN(CHGVAR VAR(&ACTION) + 


VALUE(X'FFFE')) /* If the menu user has selected option + 
90, then set the action to previous. */ 
ENDPGM /* End the program */ 


Create the CL program using the Create CL Program (CRTCLPGM) command: 
CRTCLPGM PGM(QGPL/PGMCL) SRCFILE(USERLIB/SOURCE1) 
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Creating the Menu 
Create the program menu using the Create Menu (CRTMNU) command: 


CRTMNU MENU(QGPL/PGMMENU) TYPE(*PGM) PGM(QGPL/PGMCL) 


Running the Menu 
The new display file menu can now be run using the GO command: 


GO PGMMENU 


(— > 


PG@MMENU EXAMPLE PROGRAM MENU 09:02:51 
SELECT ONE OF THE FOLLOWING: 
1. DISPLAY LIBRARY LIST (DSPLIBL) 
2. WORK WITH ACTIVE JOBS (WRKACTJOB) 
3. WORK WITH YOUR JOB (WRKJOB) 
90. RETURN 


OPTION: 


Exiting from a Program Menu without Returning to the Previous Menu 
When you code a TYPE(*PGM) menu to go from one program menu to another 
and use the RTNPNT(*NO) parameter, you need to tell the menu driver when to 
exit the original menu. 


The program menu needs to communicate with the menu driver that F3 was 
pressed. If the program menu is coded to go to program MENU2, with a 
RTNPNT(*NO), it has to be able to convey information between programs and to 
convey information to the menu driver to tell it what should be done. You can use 
data queues to communicate between the programs. For more information about 
data queues, see the CL Programming book. The following example shows you 
how to communicate between program menus if you want to use the 
RTNPNT(*NO) parameter to go from one menu to another: 
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Program 1 
PGM 


DCL VAR(&FLDLEN) TYPE(*DEC) LEN(5 0) VALUE (10) 
DCL VAR(&FIELD) TYPE(*CHAR) LEN(10) 
DCL VAR(&WAIT) TYPE(*DEC) LEN(5 0) VALUE(0) /* Don't wait */ 


/* Handle the function keys on the menu */ 
IF COND(&INO3 *EQ '1') + /* F3=Exit pressed */ 
THEN (DO) 
/* Delete the Data Queue */ 
DLTDTAQ DTAQ(QGPL/DTAQ1) 
/* Create the Data Queue */ 
CRTDTAQ DTAQ(QGPL/DTAQ1) MAXLEN(10) + 
TEXT('Test Data Queue') 
GOTO SNDDQ /* Send info to data queue*/ 
ENDDO 
/* Handle the options on the menu x/ 
IF  COND(SOPTION *EQ 1) + 


THEN(GO MENU(*LIBL/MENU2) RTNPNT(*NO) 


/* Returned from menu 2 after F3 or F12 pressed x/ 
CALL PGM(QRCVDTAQ) PARM(QGPL DTAQ1 &FLDLEN &FIELD &WAIT) 
IF COND((&FLDLEN *NE 0) *AND (&FIELD *EQ ‘EXIT ')) 


THEN(GOTO SNDDQ) 
ELSE GOTO END 


SNDDQ: DO 


/* Change the variable so the menu driver will know to */ 
/* exit and send information to the data queue to x/ 
/* communicate to next program what happened */ 


CHGVAR VAR(&ACTION) VALUE(X'FFFF') 

CHGVAR VAR(&FLDLEN) VALUE(4) 

CHGVAR VAR(&FIELD) VALUE('EXIT ') 

CALL PGM(QSNDDTAQ) PARM(QGPL DTAQ] *FLDLEN &FIELD) 


GOTO END 
ENDDO 
END: ENDPGM 
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Program 2 
PGM 
DCL VAR(&FLDLEN) TYPE(*DEC) LEN(5 0) VALUE (10) 
DCL VAR(&FIELD) TYPE(*CHAR) LEN(10) 
DCL VAR(8WAIT) TYPE(*DEC) LEN(5 0) VALUE(@) /* Don't wait */ 


/* Handle the function keys on the menu */ 
IF COND(&INO3 *EQ '1') + /* F3=Exit pressed */ 
THEN (DO) 
/* Delete the Data Queue */ 
DLTDTAQ DTAQ(QGPL/DTAQ1) 
/* Create the Data Queue */ 
CRTDTAQ DTAQ(QGPL/DTAQ1) MAXLEN(10) + 
TEXT('Test Data Queue') 
GOTO SNDDQ /* Send info to data queue*/ 
ENDDO 
/* Handle the options on the menu x/ 
IF  COND(SOPTION *EQ 1) + 


THEN(GO MENU(*LIBL/MENU2) RTNPNT(*NO) 


/* Returned from menu 2 after F3 or F12 pressed x/ 
CALL PGM(QRCVDTAQ) PARM(QGPL DTAQ1 &FLDLEN &FIELD &WAIT) 
IF COND((&FLDLEN *NE 0) *AND (&FIELD *EQ ‘EXIT ')) 


THEN(GOTO SNDDQ) 
ELSE GOTO END 


SNDDQ: DO 


/* Change the variable so the menu driver will know to */ 
/* exit and send information to the data queue to x/ 
/* communicate to next program what happened */ 


CHGVAR VAR(&ACTION) VALUE(X'FFFF') 
CHGVAR VAR(&FLDLEN) VALUE(4) 


CHGVAR VAR(&FIELD) VALUE('EXIT ') 
CALL PGM(QSNDDTAQ) PARM(QGPL DTAQ] *FLDLEN &FIELD) 
GOTO END 
ENDDO 
END: ENDPGM 


Avoiding Menu Name Conflict 


Because high-level system menus are named by full words, there is some potential 
for conflict with user-defined menu names. For example, if you use the CRTMNU 
command to create a menu called MAIN, there may be a conflict with the system- 
supplied menu, MAIN. If you use the GO command to call that menu (GO MAIN), 
the system menu MAIN will probably be shown, because it resides in the QSYS 
library. A conflict can also occur if a future release contains a new system menu 
that has the same name as a menu you created during the previous release. 


Naming Your Menus 


To avoid naming conflicts with system command menus, you should avoid menu 
names that start with CMD. The system command menu names use the format 
CMDxxxxxxx, where xxxxxxx is any subject or verb used in CL command names. 
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Placing Your Menu in a Higher Library in the Library List 
All branches to system menus from other system menus use the library list search 
order. Use of the library list search order allows multilingual support for the system 
menus. It also allows you to override a system menu by placing your own version 
of it in a library higher on the search order than library QSYS. 


Specifying the Library That Contains the Menu 
You can avoid menu name conflict by specifying the library that contains the menu 
you want to run. For example, you can use GO MENU(*USRLIBL/menu-name) to call 
user-defined menus, and use GO MENU(*LIBL/menu-name) to call system menus. 


Using the Generic Menu Specification 
When working interactively, you can use a generic menu specification on the GO 
command to avoid menu name conflict. In an example given earlier (see “Avoiding 
Menu Name Conflict” on page 9-15), a potential conflict existed between system 
and user-defined menus called MAIN. By specifying GO MAIN*, the system will 
display a list of all menu names that start with MAIN in your library list and allow you 
to select which menu you want. 


Changing the Command Default after Duplicating a Command 
You can use the Create Duplicate Object (CRTDUPOBJ) command to create a 
duplicate of the GO command for calling user-defined menus. The following 
example creates a duplicate of the GO command called GOUSR: 


CRTDUPOBJ OBJ(GO) FROMLIB(QSYS) OBJTYPE(*CMD) NEWOBJ(GOUSR) TOLIB(QGPL) 
Next, use the Change Command Default (CHGCMDDFT) command to change the 


command default for the MENU parameter to use library *“USRLIBL rather than 
*LIBL: 


CHGCMDDFT CMD(QGPL/GOUSR) NEWDFT( 'MENU(*USRLIBL/#N) ') 


With the MENU parameter default changed to *USRLIBL, the GOUSR command 
will bypass system menus and find only those menus in the user portion of your 
library list. 


Displaying Menu Attributes 


The Display Menu Attributes (DSPMNUA) command can be used to show the attri- 
butes of a menu object. These include: 


e The menu type (*UIM, display file, or program menu) 

¢ The display and message files used by display file (“DSPF) menus 

e¢ The programs used by program (*PGM) menus 

e The current (CURLIB) and product (PRDLIB) libraries associated with the menu 
e The text describing the menu object 


Changing Menu Attributes 


The Change Menu (CHGMNU) command can be used to change the attributes of a 
menu object without having to re-create the object. The attributes which can be 
changed are: 


e The current (CURLIB) and product (PRDLIB) libraries for all menu types 
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e The descriptive text for all menu types 
¢ The display and message files used by display file (“DSPF) menus 
e¢ The programs used by program (*“PGM) menus 


Deleting Menus 


The Delete Menu (DLTMNU) command can be used to delete menu objects from a 
library. The DLTMNU command can be used to delete only the menu object. Ref- 
erenced display and message files (used by display file menus) and programs 
(used by program menus) can also be deleted. 


DLTMNU is a generic command. For example, all menus in a library called OELIB 
could be deleted using the command, DLTMNU OELIB/*ALL. 


As another example, if only those menus in OELIB whose names started with ACC 
were to be deleted, the command, DLTMNU OELIB/ACC* could be used. 
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Chapter 10. Using User-Defined Data Streams 


Instead of having the system control and process the 5250 display data stream, 
you can control and process it. To do so, you must use the USRDFN keyword in 
the DDS for a display file. The data is sent to the display station using a normal 
output operation that uses the name of the record format containing the USRDFN 
keyword. When input data is received after the output operation, your program 
must determine through the input record area what was received from the display 
station. 


Note: You should be careful when using this support because error conditions can 
cause an apparent OS/400 malfunction. 


When you use the USRDFN keyword at the record level, the format does not 
contain any fields. Therefore, the buffer length of the file defaults to the length of 
the longest normal record or 100 (whichever is greater). If the user-defined data 
stream is longer than this default buffer length, you should perform the following 
steps to obtain a larger buffer length: 


e Define an externally described file, and create the program using this file and a 
record format in that file. The format should not have response indicators 
defined for it. This includes file-level indicators that are spread to all record 
formats. Any fields in the format should be defined with a field use of both 
(input and output). 


¢ Create a second file and specify LVLCHK(*NO). The second file should have two 
record formats: 


— A format with the same name as the format in the first file and which con- 
tains the USRDFN keyword. 


— A format with one field in it. The length of this field must be as long as the 
longest user-defined data stream that is to be sent to the screen. 


e¢ When you run the program, override the first file with the second display file. 


;—— Information about 5250 Display Data Streams 
For information about coding 5250 display data streams, see the following 
manuals: 


e IBM 5250 Information Display System Functions Reference. 
¢ IBM 5494 Remote Control Unit Functions Reference. 


Understanding Display Station Differences 


If you use user-defined data streams, you should be aware of the following differ- 
ences between local display stations (those attached to the display station con- 
troller) and remote display stations (those attached to remote display station 
controllers). 


¢ For local display stations, a start-of-header order length greater than 11 causes 
the negative response hex 1005012B to be sent. No negative response is sent 
for remote display stations. 
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e For local display stations, do not accept more than four field control words for 
each input-field definition. More than four causes the negative response hex 
10050130 to be sent. No negative response is sent for remote display stations. 


¢ For local display stations, self-check fields can be as long as 33 bytes for 
signed numeric fields and 32 bytes for all other fields. If the length is 
exceeded, the status response hex 00000287 is sent to the user when he or 
she tries to exit the self-check field. For remote display stations, all fields can 
be 33 bytes. 


¢ Two forms of the Request Maintenance Statistics command are supported for 
remote display stations: (1) requests that the error log area be reset, and (2) 
requests that the error log area not be reset. For local display stations, the 
error log area is always reset. 


Understanding User-Defined Data Stream Limitations 


The output record area for a user-defined record format must contain the following 
in the order specified: 


1. Display-station-specific information (required by the system), which causes the 
system to send the display-station-specific data stream to the display station. 


2. Display-station-specific data stream, which is sent to the display station. 


The USRDFN keyword is specified at the record format level and excludes for that 
record format most other functions such as the use of indicators and all field-related 
functions. However, the display file can contain other record formats not containing 
the USRDFN keyword, and the record formats can be used in any order by a 
program. When you use such a display file, you should be aware of the following: 


e When the system write routine recognizes a user-defined request, it disregards 
all previous requests to the display. At the completion of the user-defined 
request, the system assumes that a single record format is on the screen and 
that this is the record format containing the USRDFN keyword. All erasing, all 
resetting, and unlocking of the keyboard is your responsibility. The next I/O 
request can be another user-defined request or a normal field-level request. 


¢ A normal field-level request after a user-defined request is handled as follows: 


— If the OVERLAY keyword is not specified, the screen is erased before the 
request is run. 

— If the OVERLAY keyword is specified, only the portion of the display 
needed (entire lines) is erased. 

— The 5250 format buffer is reset, which means that all input fields are 
changed to output-only fields. 


The system assumes that only this record format exists on the screen. All pre- 
vious requests are disregarded. 


¢ Help specifications are allowed in user-defined record formats. 


e¢ When the USRDFN keyword is specified in a record format, no fields can be 
defined for that record format. The only valid keywords are: 


File Level Record Format Level 
KEEP ALTNAME 
OPENPRT HELP 
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File Level 


Record Format Level 


PASSRCD 
PRINT 


HLPCLR 
HLPRTN 
INVITE 
PRINT 
TEXT 


e The user-defined data stream can alter the CFnn and CAnn keys and the 
location of the message line in the display. However, display station support 
assumes they are the same as when they were last set. 


¢ All display files that contain user-defined data streams should be opened as 
both input and output files. This is because read and write commands in the 
data stream are not dependent on write and read requests. 


The output data stream should start with an escape character hex 04 and be fol- 
lowed by a clear unit hex 40 or write to display command hex 11. 


The output buffer must include information needed to send and receive the appro- 
priate line controls. The buffer format for a 5250 display station is: 


Byte 


Contents 


0-1 


2-3 


Send data length (in hexadecimal), defines the output data 
stream length 


Receive data length (in hexadecimal), defines the maximum 
input data length 


Requested function 

Hex 51 Send (WP mode) 

Hex 53 Send/Receive (WP mode) 

Hex 61 Send (3270 data stream) 

Hex 63 Send/Receive (3270 data stream) 
Hex 71 Send 

Hex 73 Send/Receive 


Output data stream 


¢ The 3270 Model 4 display station supports a display size of 43 lines by 80 
columns. If you have a 3270 Model 4 display station, you can use function 
codes 61 and 63 to write to all 43 lines. 


¢ For 3270 Model 4 display stations that are using function code 61 or 63, the 
system displays status messages on line 43. Any data that is on line 43 when 
a status message is displayed is replaced by the status message. 


e If you are using function code 61 or 63 and press the key that is defined as the 
System Request key, the key is returned to the application program instead of 
displaying the System Request menu. If you need access to the system 
request function when using function code 61 or 63, you can define the Atten- 
tion key to display the System Request menu. Before starting the application 
that uses function codes 61 and 63, specify: 


SETATNPGM SET(*ON) PGM(QSYS/QWSSYSRQ) 


When the Attention key is pressed, the System Request menu is displayed. 
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This support prohibits the use of a read operation except after a write-read(nowait) 
operation. A write-read operation that sends a read command and specifies the 
receive data length performs the operation normally performed with a read request. 
The write-read function can be performed by doing one of the following: 


Control 
Operation ILE RPG ILE COBOL Language 
SNDRCVF 
Write-read(wait) EXFMT WAIT(*YES) 
WRITE with WRITE with 
INVITE, INVITE, SNDRCVF 
Write-read(nowait) READ READ WAIT(*NO) 


Both the write-read(wait) and the write-read(nowait) operations are a combination of 
a write operation and a read operation to the same record format. When using the 
write-read(wait) operation, control does not return to the program until input is 
received from the display device. The write-read(nowait) operation is used to send 
a request for input to a display device and return to the program without waiting for 
the input to arrive. This allows a program to request input from one or more 
devices, and continue processing without waiting for any of the devices to respond. 
For each I/O request, you must make sure that the function byte and the send 
depth actually reflect the data stream sent. The receive length must be long 
enough to accommodate all data returned by the display station. If any of these is 
wrong, unexpected or unacceptable functions may happen. For example, if the 
function byte indicates a send to the display station and the data stream specifies a 
read modified command, the system sends the data stream to the display station 
and no read is performed. 


On input operations, the input buffer of the program contains the data received from 
the display station. For example, when a read modified completes, the input buffer 
contains an aid identification (AID) byte and the cursor address followed by each 
changed field. Each changed field is preceded by the buffer address order and 
field location on the screen. 


All AID bytes are accepted by display station support for user-defined data streams. 
If the Print key is pressed, the system attempts to perform the print function. 


All write and write-read operations must specify the record format name. A read 
operation that specifies the name of a record format that contains the USRDFN 
keyword and is not one of the appropriate read operations for the display station 
causes an exception to be issued. 


Each request to a 5250 display station can contain more than one command. Each 


command must be requested using the appropriate system operation identified as 
follows: 
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Output Output 
Buffer Buffer 
Send Receive 
Length Length Output Buffer 
(Bytes (Bytes Request Func- Output Buffer Command 
Operation 0-1) 2-3) tion (Byte 4) (Bytes 5-n) 
Write nn 0 71 (Send) Clear unit 
Clear format table 
Write to display 
Write error line 
Restore 
Roll 
Copy 
Write- nn nn 73 (Send/Receive) — Clear unit 
Read Clear format table 


Write to display 
Write error line 
Restore 

Roll 

Read input fields 
Read MDT fields 
Read immediate 
Save 
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Chapter 11. Passing Data between Programs 


You can use the system I/O operations to pass data between programs both in the 
same routing step of a job or across routing steps. 


Passing Data in the Same Routing Step in a Job 


To pass data between programs in the same routing step, you can either share the 
file between the programs, or you can use the KEEP and ASSUME DDS keywords 
to share a file between programs. The programs must open the same file and the 
file must be designated as a shared file. (See “Sharing Display Files in the Same 

Job” on page 3-50.) Because the programs share the file, the read operations are 
performed as described under “Reading Input from the Display” on page 3-33 and 

“Understanding How the System Reads Input from the Display” on page 3-40. 


You can also use the KEEP and ASSUME keywords to pass data between pro- 
grams. The data is written to the display by the first program, and used from the 
display by the second. 


You can use the KEEP keyword to keep data on the display for review after the 
program has ended, or you can use it to pass data between programs. 


Normally, when a file is closed, the current display is cleared. However, you can 
control this by using the KEEP keyword. If a record that is on the display when the 
file is closed has the KEEP keyword specified, the system saves the name of the 
first such record to support passing data. Using this keyword alone, you cannot 
support processing of passed data, you must also use the ASSUME keyword in the 
display file opened by the next program. 


The ASSUME keyword causes a read operation to a specific record format name to 
be valid when no preceding write operation to that record format name (or any 

other record format) has occurred since the display file was opened. The following 
shows a typical example of what happens when the ASSUME keyword is specified: 


1. Program PGM1 issues a write operation to the record format PGM1ANY in the 
display file DSPFIL1 and calls program PGM2. PGMI1ANY specifies the LOCK 
keyword. 


2. PGM2 opens DSPFIL2 and issues a read operation to record format 
PGM2ANY. The ASSUME keyword is specified. Input data is read from the 
display and processed by record format PGM2ANY. 


Records from record formats having the ASSUME keyword specified cannot overlay 
one another on the display. In addition, all records must have at least one field that 
is displayed. 


When the system reads assumed records from the display, only fields whose modi- 
fied data tags (MDTs) are on are returned. (This assumes that either the 
DSPATR(MDT) keyword was specified for the field on the last output operation or 
the user has typed in the field.) When the ASSUME keyword is in effect, the data 
returned to the program is as follows: 


e For input-only and output/input fields with their MDTs on, the changed data is 
returned. 
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e For other input-capable fields, blanks are returned for character fields and 
zeros are returned for numeric fields. 


In addition, only those fields received whose line and position on the display match 
the field of an assumed record are processed. The data is processed using the 
field descriptions in the assumed record, independent of how the fields were written 
to the display. 


For the 5250 display station, the first write operation or write-read operation after 
the file is opened sends a CA and CFnn key specification to the display station. 
Because there is no write operation after an open when using the ASSUME 
keyword, the CFnnkey specification remains as it was left by the last application. 
The CA and CFnnkey specification in this file will not be used until after the first 
write operation to the file. 


After the file is opened and the first write operation is issued, the display will be 
erased if the OVERLAY keyword is not specified. When the OVERLAY keyword is 
specified, all input-capable fields on the display become output-only fields. After 
the first write operation, assumed records cannot be read by a program. 


Fields not received from the assumed records on the display are returned to the 
user program as follows: 


Field Initialized To 

Field with DFT keyword used Value specified in DFT keyword 
Character field (no DFT keyword) Blanks 

Numeric field (no DFT keyword) Zero 

Hidden field Zero 
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Passing Data between Routing Steps in a Job 


The following example shows the steps used in passing display data between pro- 
grams in different routing steps. Note the use of the KEEP, ASSUME, and 
PASSRCD keywords. Programs PGM1 and PGM2 are user programs started by 
the subsystem SBS using different routing entries. PGM1 and PGM2 run in dif- 
ferent routing steps but are both contained in the job 000618/QUSER/WSNO1. 


Program 
PGM1 


Open DSPFIL1 


Write PGM2RD 
Close DSPFIL1 


Subsystem 
000618/QUSER/WSNO1 
Routing Routing 
Step Step 
Display File Program | 
DSPFIL1 PGM2 4 
Open DSPFIL2 
Read ... 
Close DSPFIL2 
R PGM2RD 


Display File 
DSPFIL2 


baa 


R PGM2ANY 


R PGM2RD 
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The user signs on and SBS starts a routing step based on the routing data. 
The first program in the routing step is PGM1. 


jo S| 


PGM1 opens the display file DSPFIL1. 


PGM1 interacts with the user and issues the following before ending: 
e¢ A write operation to DSPFIL1 with the record format name PGM2RD. The 


KEEP keyword is specified in the record format PGM2RD. 


Chapter 11. Passing Data between Programs 


11-3 


¢ Acclose operation to DSPFIL1. The information displayed on WSNO1 is 
not cleared because the KEEP keyword is specified in record format 
PGM2RD. 


PGM1 then ends by issuing a RRTJOB command specifying routing data that 
will cause SBS to call PGM2. 


SBS starts a new routing step based on the data supplied by PGM1 in the 
RRTJOB command. 


PGM2 opens the display file DSPFIL2. 


T PGIN2 performs a read operation to DSPFIL2 with or without the record format 
name PGM2ANY. If the record format name is not specified, the system tries 
to use the record format PGM2RD to process the data because the KEEP 
keyword was specified (in step 5). To do so, record format PGM2RD must 
exist in DSPFIL2, but it does not have to be identical to record format 
PGM2RD in DSPFIL1; only the fields that are required by PGM2 must be iden- 
tical. (If a field is returned from the display station for which no field 
description exists in PGM2ANY, the field is ignored. If the field description 
requires validation and the data received fails the validity check, PGM2 reis- 
sues a read operation to allow the current user to correct the data.) If a record 
format is not specified or if record format PGM2RD does not exist in DPSFIL2 
or does not have the ASSUME keyword specified, the data passed to the 
display station via the KEEP keyword cannot be processed. (The ASSUME 
keyword must be specified for the record format used to process passed data.) 


PGM2 processes the data and issues a close operation to DSPFIL2, which 
clears the display. 


When PGM2 ends, its routing step ends and the display returns to the control 
of SBS which shows the sign-on display. 
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Chapter 12. Waiting for Input from a Display File, an ICF File, 
and a Data Queue 
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You can use data queues for a program that waits for data on a display file, an ICF 
file, and a data queue at the same time (in any combination). When you specify 
the DTAQ parameter for the following commands: 


¢ Create Display File (CRTDSPF) command 

¢ Change Display File (CHGDSPF) command 

¢ Override with Display File (OVRDSPF) command 
¢ Create ICF File (CRTICFF) command 

e¢ Change ICF File (CHGICFF) command 

¢ Override ICF File (OVRICFF) command 


you can indicate a data queue that will have entries placed on it when any of the 
following occurs: 


e An enabled command key or Enter key is pressed from an invited display 
station. 


e Data becomes available from an invited ICF session. 


By using the IBM-supplied QSNDDTAQ program, jobs running on the system can 
also place entries on the same data queue as the one specified in the DTAQ 
parameter. 


An application program uses the IBM-supplied QRCVDTAQ program to receive 
each entry placed on the data queue and then processes the entry based on 
whether it was placed there by a display file, by an ICF file, or by the QGNDDTAQ 
program. For a display file, the application then issues a read or read-from-invited 
devices operation to receive the data. For more information on the QRCVDTAQ 
function and syntax, and examples of waiting on one or more files and a data 
queue, refer to the CL Programming book. 


The display file and ICF file entry that is put on the data queue is 80 characters 
long and contains the field attributes described in Table 12-1. Therefore, the data 
queue that is specified using the commands listed above must have a length of at 
least 80 characters. 


Entries placed on the data queue by jobs using QSNDDTAQ are defined by the 
user. 


Table 12-1 (Page 1 of 2). Display File and ICF File Entry Field Attributes 


Position Data Type Meaning 


1 through 10 Character The type of file that placed the entry on the data 
queue. This field will have one of two values: 


*ICFF (ICF file) 
*DSPF (display file) 


If the job receiving the data from the data queue has 
only one display file or one ICF file open, then this is 
the only field that needs to be used to determine 
what type of entry has been received from the data 
queue. 
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Table 12-1 (Page 2 of 2). Display File and ICF File Entry Field Attributes 


Position 


Data Type 


Meaning 


11 through 12 


Binary 


Unique identifier for the file. The value of the identi- 
fier is the same as the value in the open feedback 
area for the file. This field should be used by the 
program receiving the entry from the data queue 
only if more than one file with the same name is 
placing entries on the data queue. 


13 through 22 


Character 


The name of the display or ICF file. This is the 
name of the file actually opened, after all overrides 
have been processed, and is the same as the file 
name found in the open feedback area for the file. 
This field should be used by the program receiving 
the entry from the data queue only if more than one 
display file or ICF file is placing entries on the data 
queue. 


23 through 32 


33 through 42 


Character 


Character 


The library where the file is located. This is the 
name of the library, after all overrides have been 
processed, and is the same as the library name 
found in the open feedback area for the file. This 
field should be used by the program receiving the 
entry from the data queue only if more than one 
display file or ICF file is placing entries on the data 
queue. 


The program device name, after all overrides have 
been processed. This name is the same as that 
found in the program device definition list of the 
open feedback area. For file type *DSPF, this is the 
name of the display station where the command or 
Enter key was pressed. For file type *ICFF, this is 
the name of the program device where data is avail- 
able. This field should be used by the program 
receiving the entry from the data queue only if the 
file that placed the entry on the data queue has 
more than one device or session invited prior to 
receiving the data queue entry. 


43 through 80 
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Character 


Reserved 


Chapter 13. Using Alternative Character Sets and Code 
Pages 


In multinational environments, data in one national character set may need to be 
displayed or entered on display stations that support another national character set. 
This is particularly true of characters with accents and other characters with 
diacritical marks (such as c with a cedilla, n with a tilde, and u with an umlaut). In 
this section, these characters are called extended alphabetics. 


For example, assume that a physical file on the system contains data in the Basic 
French code page, and includes an é (e with an acute accent). In the Basic French 
character set, this character is hex CO. The data could have been entered on a 
display station that can handle the character or could have been sent to this system 
from another system over a communications line. 


Note: On some display stations, extended alphabetics can be entered on the key- 
board (by pressing Cmd, then the key to its right with two diacritical marks 
on it, then the 2 hexadecimal digits that represent that character). 


Display 
Station Physical File 
(| 
LL J > Containing 
= Hex CO (é) 
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When the hex CO is sent to a display station that does not recognize hex CO as é, 
the hex CO is not displayed as é. For example, a display station that recognizes 
the U.S. code page displays hex CO as { (a left brace). The é is at code point 51 in 
the U.S. code page. To properly display é, the hex CO must be converted to hex 
51 for display on a U.S. basic display station. 


With the IBM-supplied conversion tables, the system can convert most extended 
alphabetics, but not all. If an extended alphabetic character does not have a 
clearly preferable equivalent, the system converts the character to a (-) hyphen. 


System Has Characters Not Normally Displayed on the Device: The case of an 
output/input field shows how character conversion occurs at a display station. 


Display 
: Application File Display 
Physical Program Station 
File 
a) 
Read 3 Write | | | 


. 5 Renee 
; >| Renee > | Renee - (oO _ 
Renee : 
Lf i | AVENE 
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Assume that a record in a physical file contains a field with the value Renée. An 
application program reads the record from the physical file, and writes a record 
containing the data to the display file. One way to achieve character conversion is 
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in the DDS for the display file, the output/input field in which Renée appears has 
the Character Identifier (CHRID) keyword specified.! This keyword asks the system 
to perform character conversion if needed. Character conversion is needed if the 
CHRID parameter value for the display file differs from the CHRID value of the 
display station. In this case, character translation is needed because the display 
file has CHRID(288 297), which is the basic French code page and character set, 
and the device description has CHRID(101 37), which is the basic U.S. code page 
and character set. 


When displaying the data, the system converts the hex CO to hex 51, and Renée 
appears on the display. If no conversion occurred, Ren{e would appear on the 
screen. 


On input, one of the following occurs: 


e lf the modified data tag (MDT) is turned on for the field (this happens when the 
user types into the field or if the DSPATR(MDT) keyword is in effect for the 
field) the contents of the field are converted from the device CHRID to the 
CHRID parameter value specified on the Display File (DSPF) command and is 
returned to the program. 


e lf the modified data tag (MDT) is not turned on for the field, the saved contents 
of the field (with original, untranslated, data) is returned to the program. 


Another way to achieve character conversion on a file basis is to specify the 
*JOBCCSID value on the CHRID parameter for the Create Display File 
(CRTDSPF), the Change Display File (CHGDSPF), or the Override Display File 
(OVRDPSF) commands. More information about *JOBCCSID is in “Specifying 
Character Translation for Fields” 


Device Passes Characters Not Displayed on the System: lf the user can enter 
data not normally displayed on the system (for instance, a user on a French- 
language display station in Montreal dials up a remote line to a system in Toronto 
with display stations that cannot display extended alphabetics), no change occurs 
when the data is sent to the system. The program can read data from the French- 
language display station and write it to a physical file. However, when another user 
on the Toronto system displays data from the physical file, the system attempts to 
translate the data for the display station that cannot display extended alphabetics. 


Specifying Character Translation for Fields 


If the CHRID keyword is specified on a field, character conversion occurs only if the 
CHRID parameter value in the display file is different from the CHRID value in the 
device description. 


1. The CHRID parameter on the display file is set by the CHRID parameter on the 
CRTDSPF, CHGDSPF, or OVRDSPF command. The CHRID parameter can 
have one of the following values: 


1 If *JOBCCSID is specified by the CHRID parameter on the CRTDSPF, CHGDSPF, or OVRDSPF commands, the DDS keyword 
CHRID is ignored. For more information, see the description for *“JOBCCSID in “Specifying Character Translation for Fields” on 
page 13-2. 
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“DEVD (the default): Use the CHRID parameter specified on the device 
description on which the application is currently running. No character con- 
version occurs. Any CHRID keywords specified in the DDS are ignored. 


“SYSVAL: Use the character set and code page specified in the system 
value QCHRID on which the application is currently running. Specify the 
CHRID keyword in the DDS for the display file fields that will need conver- 
sion. Constants are not converted. 


*JOBCCSID: Use the character set and code page specified by the job. 
This allows named fields and unnamed (constant) fields to be automatically 
translated when the job CCSID or the display file CCSID does not match 
the device description CHRID. If the job CCSID does not match the device 
description CHRID, named fields are translated from the job CCSID to the 
device description CHRID on output and conversely on input. If the display 
file CCSID does not match the device description CHRID, data in the 
display file is translated from the display file CCSID to the device 
description CHRID on output. When *JOBCCSID is specified, the DDS 
CHRID keyword is ignored. Use the No Coded Character Set Identifier 
(NOCCSID) keyword on named and unnamed fields that you do not want 
translated. 


Character set and code page: Use the character set and code page speci- 
fied. See Table 13-1 on page 13-5 for the list of valid values. 


2. The CHRID value on the device description is set by the CHRID parameter on 
the Create Device Description Display (CRTDEVDSP) or Change Device 
Description Display (CHGDEVDSP) command. This parameter can have one 
of the following values: 


“SYSVAL: Use the character set and code page specified in the system 
value QCHRID. 


*“KBDTYPE: Use the character set and code page specified in the key- 
board language prompt (KBDTYPE). This value corresponds to the country 
keyboard language identifier. 


Character set and code page: Use the character set and code page speci- 
fied. See Table 13-1 on page 13-5 for the list of valid values. 


When dealing with UCS-2 Level 1 data from a physical file, it will be necessary to 
convert this data to EBCDIC before displaying the data on the screen. To accom- 
plish this conversion, place the DDS CCSID keyword at either the file-, record-, or 
field-level to enable conversion of UCS-2 data from the UCS-2 CCSID value speci- 
fied with the keyword to the device CHRID on output. On input, the data is con- 
verted from the device CHRID to the UCS-2 value. For more information, see 
“UCS-2 Level 1 Considerations for DDS” in the DDS Reference book. 


Another conversion that occurs every time data is displayed is converting the hex 
“SF” character to the hex “1F” character on output and conversely on input. The 
Character Data Representation Architecture (CDRA) specifies the hex “3F” char- 
acter as a replacement character. This character is also a field attribute definition 
for the 5250 data stream specification. Translation to convert hex “3F” character to 
hex “1F” character for output is done for all fields whether *“JOBCCSID translation is 
active or inactive. Use the NOCCSID keyword to prevent translation at the field 
level. 
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When character conversions are necessary, the system uses a conversion table in 
library QUSRSYS to convert the data. The name of the conversion table used is 
derived from parts of the source and target CCSID for which the table is needed as 
shown in the following example: 


On Output: 


Display File Device Description 


Jf )~CHRID(101 037) 
CHRID(288 297) 


Translation Table Used: Q297101037 


On Input: 


Display File Device Description 


CHRID(101 037) 
CHRID(288 297) 


Translation Table Used: Q037288297 
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IBM supplies a number of tables in library QUSRSYS to handle conversion among 
the most frequently used combinations of character sets and code pages. If you 
need to tailor the way characters are converted, you can create your own table in 
library QUSRSYS, using the Create Table (CRTTBL) command to do the conver- 
sion. To determine what conversion tables are available to use, look in the 
QUSRSYS library for object type *TBL. 


Determining the Character Identifier (CHRID) Value for Your Display 


The CHRID value specified should be based on the attributes of the display station. 
The table below shows CHRID values that are appropriate for each display station 
keyboard type. For some display stations, you do not need to specify the 
KBDTYPE parameter, but the KBDTYPE value for the equivalent keyboard can be 
used to determine the CHRID value for the display station: 
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Table 13-1. CHRID Values 


Language/Country Keyboard Type (KBDTYPE) SURI: Full CHRID 
International and US ASCII INB 103 038 697 500 
Multinational AGI BLI CAI DMI FAI FNI FQI ICI INI 697 500 
IT| JEL NEl NWI PRI SFI SGI SPI SSI 
SWI UKI USI 
Arabic CLB 235 420 
Austria/Germany AGB 265 273 697 273 
Belgium Multinational BLI 697 500 
Canada/French CAB 277 260 341 260 
Cyrillic CYB 960 880 
Denmark/Norway DMB NWB 281 277 697 277 
Finland/Sweden FNB SWB 285 278 697 278 
France FAB FQB 288 297 697 297 
Greece GKB 218 423 
Hebrew NCB 941 424 
Iceland ICB 697 871 
Italy ITB 293 280 697 280 
Japan/English JEB 297 281 697 281 
Japan/Kanji JKB (For Personal System/55*, 5295 and 332 290 
3477-J display stations) 
Japan/Katakana KAB (For 5251, 5291, 5292, and 3180 332 290 
Katakana display stations) 
Korean KOB 933 833 
Latin 2 ROB 959 870 
Netherlands NEB 697 037 
Portugal PRB 301 037 697 037 
Simplified Chinese RCB 936 836 
Spain SPB 305 284 697 284 
Spanish Speaking SSB 309 284 697 284 
Switzerland/French Multinational SFI 697 500 
Switzerland/German Multinational SGI 697 500 
Thai THB 938 838 
Traditional Chinese TAB 101 037 
Turkey TKB 965 905 
United Kingdom/English UKB 313 285 697 285 
United States/English USB 101 037 697 037 
Countries of the former Yugoslavia YGI 959 870 
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Chapter 14. Improving System Performance with Displays 


System performance is improved by doing the following: 


e Minimizing the number of bytes sent and received when designing a display. 
For example, to reduce the number of fields on an application display: 


— Split a display with many fields into more than one display. 


— Consider removing fields which were added to help with development, 
testing, or problem reporting. 


e Taking advantage of the system functions that reduce the number of bytes sent 
to and received from the display station. This chapter describes some of these 
system functions. 


Deferring the Write Operation for a Display File 


The DFRWRT parameter on the Create Display File (CRTDSPF) or Change 
Display File (CHGDSPF) command allows you to delay the writing of data to the 
display until needed. Deferring the write operation is useful when the final display 
shown at the display station is formed by several record formats being written to 
the display. 


Using DFRWRT(*YES) on a display file improves systems performance in some 
cases. 


More information on the Defer Write parameter can be found in “Deferring the Write 
Operation Until a Read Request is Made” on page 3-26. 


Designating the Primary Screen Size for a Display File 


Normally, the display files are set up for a 24 by 80 screen (default size). The 
DSPSIZ keyword specifies which display sizes are valid for a file and indicates 
which sizes are the primary and secondary screen sizes. (The primary screen size 
is the first or only DSPSIZ value.) On the DSPSIZ keyword, the screen size can be 
specified as *DS3, *DS4, 24 80, or 27 132. For example, DSPSIZ (24 80) specifies 
a screen size of 24 by 80. 


The screen size designated as the primary screen size should be the one with 
which the display file will most often be used. A performance benefit will be real- 
ized by coding the DSPSIZ keyword in this manner. Additional processing is per- 
formed when the actual screen size is the secondary screen size. 


Writing Only One Page of Subfile Records at a Time 


A technique to improve performance when you are using a multiple page subfile is 
to write only one page of subfile records at a time but use the OS/400 support to 
roll through the subfile. To do this, you need to define the ROLLUP keyword in 
DDS with a response indicator and also use the SFLRCDNBR keyword. In your 
program, you would write the records needed to fill one subfile page and then 
display that page. When the user wants to see more records, he or she presses 
the Roll Up key. The program then writes another page of records to the subfile, 
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places the relative record number of a record from the second page into the 
SFLRCDNBR field, and displays the record. 


The second page of subfile records is now displayed, and if the user presses the 
Roll Down key, the roll down is handled by the system. If the user presses the Roll 
Up key while the first page is displayed, the system will also handle the roll up. 

The program is notified only when the user attempts to roll up beyond the records 
currently in the subfile. The program would then handle any additional roll up 
requests in the same manner as for the second page. When you use this tech- 
nique, the subfile appears to be more than one page because of the use of the roll 
keys. Yet, you can maintain good response time because the program only fills 
one subfile page before writing it to the display. 


Sharing an Open Data Path (ODP) for the Same Job 


OS/400 data management support offers a close level of sharing within a job that 
allows more than one program to share the same path to the data or display 
station. By specifying “YES for the SHARE parameter on the Create Display File 
(CRTDSPF) command, the Change Display File (CHGDSPF) command, and the 
override file commands, more than one program can share the file status, positions, 
and storage area. Performance is improved by reducing the amount of main 
storage the job needs and the time it takes to open and close the file. 


Note: To use SHARE(*YES) to improve performance, you need to define many 
record formats within the display file. However, the program may not use 
all the record formats in the display file, even though the program has work 
storage allocated for all the record formats defined in the display file. This 
causes the PAG storage associated with the job to be larger, which can 
adversely affect performance. 


More information about sharing open data paths is found in “Sharing Display Files 
in the Same Job” on page 3-50. 


Sending Records with Input Fields to the Display in Order 


Records containing input fields should be sent to the display station in the order in 
which they appear on the display. This technique provides better performance than 
if record formats with input fields are sent randomly or in some other order. 


Overlapping and Not Deleting Repeatedly Sent Records 


You can use the CLRL(*NO) keyword to prevent an overlapped record from being 
deleted when the overlapping record is written to the display. If you use this 
keyword, any records being displayed that are to be overlapped are not deleted 
from the screen; the new record overlays them entirely or partially. There is a per- 
formance advantage to using CLRL(*NO) if you have a display that contains con- 
stants and data that is repeatedly sent to the screen. By sending the constants as 
a separate format and using CLRL(*NO) for the format containing only the data, 
you can reduce the time required to send the record format to the display. 


The use of the PUTOVR keyword causes only those fields for which the OVRDTA 
or OVRATR keyword have been specified to be sent to the display when a subse- 
quent write or write-read operation is issued to the same record format. 
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You can also use the OVERLAY keyword to clear only that portion of the display 
affected by the record format being written. 


You can use ERASEINP to improve response time by causing the display to clear 
fields instead of requiring blanks to be sent to the display. If the fields erased at 
the display do not have their modified data tags set on for the next read operation, 
data is returned for those fields from the input save area. This is data saved by the 
system from the previous return of the field from the display station. 


You can use the INZINP keyword at the record level with ERASEINP(*ALL) and 
PUTOVR to initialize the input save area without sending data for the cleared fields 
to the display. 


Restoring the Display 


When *YES is specified for the Restore Display (RSTDSP) parameter, an image of 
the current display is saved when the display is suspended. When the display file 
is activated again, the saved image is used to restore the display to its appearance 
before being suspended. 


The RSTDSP(*YES) parameter must be specified for the following keywords. If the 
parameter is not specified, data on the display can be lost if the file is suspended. 


e CLRL 

¢ OVERLAY 

« PUTOVR 

e PUTRETAIN 
« ERRMSG 

¢ ERRMSGID 


If none of the previous keywords are used, you can improve performance by speci- 
fying *NO for the RSTDSP parameter. 


Defining Command Attention Keys Rather Than Command Function 


Keys 


Command attention (CAnn) keys return only the indication of the key pressed and 
not data. Command function (CFnn) keys cause all input data to be returned. If 
you only need to detect a function key and do not need to return data from the 
display, define keys as command attention keys. 


Using the Invite Operation 


The invite operation, specified by the INVITE keyword, allows the program to be 
responsive to various display station and system events. The invite operation also 
allows the program to process between the last WRITE and READ operations. 
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Using Windows 


DDS-described windows may improve performance because they only affect the 
portion of the display where they are placed. 
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Chapter 15. Improving Productivity with User Interface 
Manager 


Using the user interface manager (UIM) can improve user and application pro- 
grammer productivity. 


Increasing User Productivity 


The UIM controls the panel's appearance and assures consistency with panels 
developed by IBM. This gives an application a consistent user interface which 
increases user productivity. 


Increasing Application Programmer Productivity 


Application programmer productivity is increased by using the UIM to create panels. 
The application programmer can describe the contents of a panel without specifying 
all the details. The format of the panel's elements is handled automatically by the 
UIM. For more information on the panel elements that UIM handles, see “What the 
UIM Supports” on page 16-2. 


Using the UIM language tags allows the application programmer to "link" an option 
number or function key to a specific command or program. Then, when a user 
selects an option or presses a function key, the UIM automatically handles running 
the command or program. The UIM also handles scrolling through a multiple-page 
panel. The Major Command Groups menu is an example of a multiple-page panel. 


What to Consider before Using UIM Instead of Data Description 
Specifications (DDS) 


The UIM and DDS each use a different source language to create interactive dis- 
plays. Display functions in interactive applications can be built using DDS, a com- 
bination of DDS and UIM, or only UIM. With DDS, the application programmer can 
customize display screens, and with UIM, the display screens are automatically for- 
matted resulting in a consistent appearance. In addition, the UIM performs more 
dialog management functions than DDS, so using UIM results in less application 
programming. 


The UIM supports the following types of display screens (or panels). Each one can 
be scrollable or nonscrollable: 


e List 

e Menu 

e Information 
e Data entry 


For more information on creating these display screens, see Chapter 16, “Introduc- 
tion to the User Interface Manager” on page 16-1. 


Consider the following before using UIM: 


e lf you are creating a new application, the UIM simplifies making display screens 
standard. 
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e lf you are rewriting an old application, evaluate the effort involved to rewrite the 
display screens versus the productivity benefits already described. In some 
cases, conversion to UIM may not be warranted unless a major redesign or 
rewrite of an application is required for other reasons. 


¢ Because UIM was designed for 525x nonprogrammable workstations, using 
UIM does not appreciably simplify converting an application oriented to a pro- 
grammable workstation except by ensuring standard display screens. 


e lf an application program makes extensive use of database files, UIM does not 
take advantage of file descriptions the way DDS does. 


e Using UIM to create data panels should be for low frequency and low volume 
output/input. Nonscrollable data entry applications with high frequency and 
volume of interactions should consider using display files created from DDS for 
the best performance. This is because the UIM does not accept high fre- 
quency and high volume keyboard input as quickly as DDS does. That is, the 
UIM may not be able to accept keyboard input as quickly as the user can type 
it. However, a keyboard with type-ahead function may compensate for this. 


The following lists some of the advantages and differences between using UIM or 
DDS: 


e UIM Advantages 


— Uses same standards as system so no need to redefine standards. User 
applications work the same way as the system panels. UIM formats panels 
based on what you want displayed. 

— List processing offers ability to process commands, to prompt or call pro- 
grams easily from a list panel, to specify programs for UIM to call after 
option is selected, and allows more efficient list entry access or update pro- 
cessing. 

— Operates well with languages that efficiently process structures. 

— Provides for more modular programming techniques (one program can 
process all incomplete list exit calls, open all applications, and so on). 

— Offers ability to condition menu options 

— Formats and handles scrolling of large areas without user program inter- 
vention (data, list, info, menu, and function key areas, for example). 


e DDS Advantages 


— Provides more flexibility in screen design 

— SDA helps in initial formatting 

— Ability to use UIM help or help in folders 

— Ability to take advantage of GUI windows 

— Subfile processing 

— Use of EDTCDE and EDTWRD and user-defined editing 
— Faster for smaller applications since set-up time is less. 


For additional factors to consider when using UIM, see “Choosing between Panel 
Groups, Documents, and Records for Help” on page 18-2. 
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Chapter 16. Introduction to the User Interface Manager 


This chapter gives an introduction to the user interface manager (UIM) that IBM 
uses to develop the AS/400 panels. It explains what the UIM provides to make 
creating and managing panels easy and also gives the panels the look of an 
AS/400 panel. 


For detailed information on the UIM, see Chapter 17, “Details of Using User Inter- 
face Manager” on page 17-1. 


For information on using the examples mentioned in this chapter, see source 
member T0011INF in source file QATTINFO in library QUSRTOOL. 


Overview of UIM 


The OS/400 UIM is a part of the system that allows you to define panels and 
dialogs for your application and provides the following support: 


e A tag-based language for describing data and panels. 


¢ Acompiler to create panel group objects and menu objects using the tag-based 
language. 


¢ A set of application programming interfaces (APIs) to use as panel group 
objects to display and print panels. 


e¢ The UIM also provides the following functions: 


— Dialog commands for screen management 

— Contextual online help 

— Index search 

— Access to InfoSeeker 

— Pop-up windows 

— Menu bars 

— Command line for entering CL commands 

— Tailoring of the contents of a panel for different users or environments 
— Fast paths through menu networks 

— Double-byte character set (DBCS) languages 
— Bidirectional (BIDI) language support 

— Graphical user interface (GUI) support 

— UCS-2 support 


UIM supports common panel types, such as menus, information displays, list dis- 
plays, and entry displays. When all display types and interfaces are consistent, 
users adapt more quickly to new applications. 


UIM applications can coexist with and share the requester display device with other 
open display files that are not under UIM control. However, a UIM panel and a 
DDS-defined record format cannot appear on the display at the same time. When 
a UIM panel replaces a DDS panel or vice versa, the system suspends operations 
of one file or panel group and restores the display as needed. 
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What the UIM Supports 


When you design a panel, the UIM provides the correct placement and format of 
many panel elements, such as: 


e Panel name 

e Panel title 

¢ Separator lines 
¢ Column headings 
e Entry fields 

¢ Command line 

e Message line 

e Function keys 

¢ Pop-up windows 
e Menu bars 

e Pull-down menus 


In addition, the UIM provides the following support: 
¢ Correct placement of the cursor 


The user interface style has several rules for positioning the cursor which UIM 
supports. 


¢ Cursor-sensitive help information 


Depending on where the cursor is located when the Help key is pressed, the 
user interface style has rules for what type of help information is displayed. 


¢ Scrolling 

e Fast paths through menu networks 

e National language considerations to make translating easier 

¢ Windows for help information and application panels 

e¢ 132-column panels 

¢ Left-to-right and right-to-left (bidirectional) national language formatting 

e Hypertext links 

¢ Control over left-to-right and right-to-left orientation of text 

¢ Ability to create online help information 

e Ability to enable a panel for conversion to a graphical user interface (GUI) 


What Is a Panel Group 


A panel is a visual presentation of data on the screen. A panel group is an object 
that contains a collection of display formats, print formats, or help information. The 
system-recognized identifier for the object type is “*PNLGRP. 


For detailed information on the panel group (PNLGRP) language tag, see 
“PNLGRP (Panel Group)” on page A-139. 


What Is a Menu 


A menu is an object that contains the definition of a panel which contains one or 
more options. The user can select an option from the panel in order to start using 
a program or command, or to go to another menu. The system-recognized identi- 
fier for the object type is *MENU. 
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The OS/400 program provides the GO command to display a menu. Therefore, no 
application program is necessary to display and handle the user interaction for a 
menu. 


You can define the following types of menus using the Create Menu (CRTMNU) 
command. 


*DSPF An existing display file (*DSPF) and message file (*MSGF) are used to 
display the menu. 


*PGM The OS/400 program calls an application-defined program to display the 
menu. The program is responsible for displaying the menu to the user 
and processing options requested by the user. 


*UIM The menu object is created using a member in a source file that con- 
tains a description of the menu. The source describes the menu using 
the UIM tags. 


This chapter discusses how to create a *UIM type of menu. For information on 
how to create a *DSPF or *PGM type of menu, see Chapter 9, “Creating and 
Accessing Menus Using Display Files” on page 9-1. 


Creating Objects 
The UIM creates and changes the following objects: 


e¢ Panel group objects 
e Menu objects 
e Search index objects 


The panel group and menu objects contain panel definitions and online help infor- 
mation. A menu object (*MENU), which contains a panel group definition, is 
created using the TYPE(*UIM) parameter on the Create Menu (CRTMNU) 
command. The panel group and menu objects are created using a tag-based lan- 
guage that specifies definitions for UIM elements. 


The UIM creates search index objects that contain search terms extracted from 
online help information. A search index object makes it more efficient for a user to 
locate specific online information using the index search function. 


Elements Within a Panel Group 


The tag-based language used to define the panels, menus, and online help also 
supports definitions of symbolic elements that include the following: 


e Variable classes 

e Data elements that can be accessed through the UIM application programming 
interface (API), such as dialog variables and lists 

e Variable records that define buffers passed by application programs 

¢ Conditional expressions that must be true if certain processing is to take place 

e Key lists containing the definition of function keys 

e Menu bars containing the definition of one or more pull-down menus 

e Panel definitions containing one or more areas to present data, information, 
lists, and menus 

¢ Online help text modules 
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Using the UIM Language Tags 


The language tags are an easy-to-use function for defining panels. Using the lan- 
guage tags helps application programmers create consistent appearing panels. For 
more information on the language tags, see Appendix A, “UIM Panel Group Defi- 
nition Language” on page A-1. 


Using Dialog Commands 


Dialog commands are special functions, recognized only by the UIM, that allow the 
user to navigate through the panels. 


Following is a list of the dialog commands and the functions they perform: 


ACTIONS 
CALL 
CANCEL 
CHGVIEW 
CMD 
CMDLINE 
DSPHELP 
ENTER 
EXIT 
EXTHELP 
HELP 


HELPHELP 
HELPIDX 


HOME 
KEYSHELP 


MENU 
MOREKEYS 
MOVETOP 
MSG 
PAGEDOWN 
PAGEUP 
PRINT 
PROMPT 
PULLDOWN 


RETRIEVE 
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Alternates the cursor position between the panel and the menu 
bar; removes, if shown, a pull-down menu from the panel. 

Calls an application program to perform a function. 

Backs up one panel (returns to the previous panel). 

Changes the displayed view of a list by switching defined sets of 
columns to be shown. 

Submits an AS/400 CL command (or System/36 environment 
OCL command) to the system for processing. 

Displays a pop-up window with a command line. 

Displays a module of help text. 

Initiates processing of an action; submits panel input for pro- 
cessing. 

Returns the user from a group of displays or menus. 

Displays the extended help text for the panel. 

Displays help information for the panel, based on the position of 
the cursor. 

Displays information about how to use the help facilities. 
Initiates the index search function for the application to allow the 
user to make a search request. 

Displays the initial (home) menu of the job. 

Displays the help for the function keys shown on the displayed 
panel. 

Displays a subsequent menu as a result of selecting a menu 
item or pressing a function key. 

Displays an additional set of active function keys and their 
descriptions; used when all keys cannot be shown at once. 
Moves a cursor-selected line to the top of the scrollable informa- 
tion area. 

Displays a message on the message line. 

Pages (scrolls) forward by one panel. 

Pages (scrolls) backward by one panel. 

Prints all the information shown on the current display. 

Prompts (seeks input) for commands, action list options, or entry 
fields. 

Displays the pull-down menu for the first choice shown on the 
menu bar. 

Retrieves and displays the previously entered command. 


RETURN Returns control (and a return value) to an application for pro- 
cessing. 
Note: To provide the Refresh/Redisplay function for an applica- 
tion, use the RETURN dialog command. 


For detailed information on the dialog commands, see Appendix B, “UIM Dialog 
Commands.” 


Using Control Language (CL) Commands 


The following CL commands are used to work with panel groups, menus, index 
search, and InfoSeeker: 


¢ ADDSCHIDXE (Add Search Index Entry) 

¢ CHGMNU (Change Menu) 

¢ CHGSCHIDX (Change Search Index) 

e¢ CRTMNU (Create Menu) 

e CRTPNLGRP (Create Panel Group) 

¢ CRTSCHIDX (Create Search Index) 

e DLTMNU (Delete Menu) 

e DLTPNLGRP (Delete Panel Group) 

¢ DLTSCHIDX (Delete Search Index) 

¢ DSPMNUA (Display Menu Attributes) 

¢ GO (Go to Menu) 

¢ RMVSCHIDXE (Remove Search Index Entry) 
e¢ STRINFSKR (Start InfoSeeker) 

¢ STRSCHIDX (Start Search Index) 

¢ WRKSCHIDXE (Work Search Index Entry) 


For detailed information on the CL commands, see the CL Reference. 


Using an Application Programming Interface (API) 


The UIM provides several API services. The service calls to the UIM consist of the 
following: 


e Application services 
e Variable pool services 
e List services 

e Display services 

e Print services 


The application services consist of the following: 


¢ Open Display Application (QUIOPNDA) 
¢ Open Print Application (QUIOPNPA) 
¢ Close Application (QUICLOA) 


The variable pool services consist of the following: 


¢ Get Dialog Variable (QUIGETV) 
e Put Dialog Variable (QUIPUTV) 


The list services consist of the following: 


¢ Add List Entry (QUIADDLE) 
¢ Add List Multiple Entries (QUIADDLM) 
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¢ Get List Entry (QUIGETLE) 

¢ Get List Multiple Entries (QUIGETLM) 
e Update List Entry (QUIUPDLE) 

¢ Remove List Entry (QUIRMVLE) 

¢ Delete List (QUIDLTL) 

¢ Set List Attributes (QUISETLA) 

¢ Retrieve List Attributes (QUIRTVLA) 


The display services consist of the following: 


¢ Display Panel (QUIDSPP) 

Display Help (QUHDSPH) 

Add Pop-up Window (QUIADDPW) 
Remove Pop-up Window (QUIRMVPW) 
Set Screen Image (QUISETSC) 

¢ Display Long Text (QUILNGTX) 


The print services consist of the following: 


¢ Print Panel (QUIPRTP) 

° Print Help (QUHPRTH) 

¢ Add Print Application (QUIADDPA) 

¢ Remove Print Application (QUIRMVPA) 


For details on the APIs, see the System API Reference. 


Defining a Menu Object Using UIM 


Using the UIM, you can create a *UIM type of menu object. The menu object con- 
tains the definition of a menu panel with one or more options. To create a *UIM 
type of menu, do the following. 


1. Create a member in a source physical file. 


2. Enter the UIM tag source to describe the menu using a source editor, such as 
the Source Entry Utility (SEU). An example menu exists in member T0011MN2 
in file QATTUIM in library QUSRTOOL. You can copy this example to use as a 
template to create your own menu. 


3. Use the Create Menu (CRTMNU) command to create the menu object using 
the tag source as input. Here is an example of using the CRTMNU command. 


CRTMNU MENU(MYLIB/MYMENU) TYPE(*UIM) SRCFILE (MYLIB/QMNUSRC) 


The source member defaults to the name of the menu being created. 


Creating a Menu Panel 


The panel shown in Figure 16-1 on page 16-7 is an example menu. If you need 
more information on creating help for a menu area, see “Help in a Menu Area” on 
page 19-7. 
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TOOLIMN2 Example Menu [qj 
System: | SYSNAMXX 
Select one of the following: [J 


1. Work with members in a file [jj 
2. Work with record definitions 


Selection or command [J 
===> 


F3=Exit F4=Prompt  F9=Retrieve F12=Cancel 
(C) COPYRIGHT YOUR COMPANY NAME HERE, 1992. 


Figure 16-1. An Example Menu 


The reference numbers in the example menu do not appear on the display. They 
are shown for illustration purposes and also appear in the UIM tag source shown in 
“Source for Example Menu” on page 16-9. These reference numbers show the 
portions of the source which define text and information that appear on the menu. 


The panel identifier is defined by declaring the UlM-defined Z-variable, 
ZMENU, using the VAR tag and specifying the Z-variable to be used as the 
panel identifier on the PANELID attribute of the PANEL tag. 


The panel title is defined as text following the period of the PANEL tag. 


jo S| 


The system name is shown because the TOPSEP=SYSNAM attribute was 
specified on the PANEL tag. 


The top instruction line is defined as text following the period of the top 
instruction (TOPINST) tag. 


Each option on the menu is defined using the menu item (MENUI) tag. The 
option number is defined using the OPTION attribute and the text following the 
option number is defined as text following the MENUI tag. 


The command line is defined using the command line (CMDLINE) tag. The 
command line prompt text is defined as text following the CMDLINE tag. The 
UIM automatically provides the arrow (===>) for every command line. 


An option line can be defined by using the option line (OPTLINE) tag instead 
of the CMDLINE tag. In this case, the user enters option numbers, but is not 
allowed to enter system commands. 


Each function key is defined using a key list item (KEYI) tag. The text, 
including the function key name, is defined as text following the period of the 
KEYI tag. 


All function keys for a panel are defined by placing the KEYI tags between a 
key list (KEYL) and EKEYL tag. The name specified on the NAME attribute of 
the KEYL tag is also specified on the KEYL attribute of the PANEL tag. 
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Some function keys, such as the Enter key, do not have text specified for the 
KEYI tag. In this case, no text appears on the display. However, all function 
keys must be defined using the KEYI tag so the UIM knows what action is 
assigned for each key and what help module should be displayed when help 
is displayed for the function keys. 


EF] The copyright message is defined as text following the period of the copyright 
(COPYR) tag. The copyright message is displayed once when the user ini- 
tially sees the menu. The message is not shown when the menu is redis- 
played after processing an option or command. 


This example menu is not defined as scrollable because it contains only two 
options. If you need to define a scrollable menu, change SCROLL=NO to 
SCROLL=YES on the MENU tag and add one menu item (MENUI) tag for each 
additional menu option. You also need to define a new help module for each menu 
option. 


Required Tags for a Menu Panel 


Figure 16-2 shows the required tags for creating a UIM menu panel. For an 
example of the required and optional tags, see “Source for Example Menu” on 
page 16-9. 


Note: The tags in Figure 16-2 require attributes. These attributes are not shown. 
Without these attributes, the example in Figure 16-2 will not compile. For a 
description of the required attributes for these required tags, see 
Appendix A, “UIM Panel Group Definition Language.” 


:PNLGRP. 


: EMENU. 
SOPTLINE or :CMDLINE. 
:EPANEL. 


:HELP. 


SEHELP. 


:EPNLGRP. 
Figure 16-2. Required UIM Tags for a Menu Panel 


16-8 Application Display Programming V4R1 


Source for Example Menu 


This is a listing of the tag source for the menu shown in Figure 16-1 on page 16-7. 
The entire source can be found in member T0011MN2 in source file QATTUIM in 


library QUSRTOOL. 


.* Beginning of menu source. 
it 


Kk ene 


:PNLGRP = HLPSHELF=LIST 
DFTMSGF=t0011msgf2 
SUBMSGF=t0011msgf2. 


x 


KK eee eee 


-* Copyright statement appears when the menu is initially displayed. 
KR eww ww ew eee ee ee ee ee ee ee ee ee ee ee ee ee ee ee eee ee ee ee ee ee ee ee 


:COPYR. [q 


(C) COPYRIGHT YOUR COMPANY NAME HERE, 1992. 


x 


aK eee eee ee ee ne eee 
.* UIM Z-variable to be used as the panel identifier 


:VAR NAME=ZMENU. 

* 

WK cece eee ee 
.* Define keys for the menu 

WK eee eee nee 


KEYL NAME=menukeys 
HELP=keyl. 

:KEYI KEY=F1 
HELP=helpf1 
ACTION=HELP. 

:KEYI KEY=F3 
HELP=exit 
ACTION='EXIT SET' 
VARUPD=NO. 

F3=Exit 

:KEYI KEY=F4 
HELP=prompt 
ACTION=PROMPT. 

F4=Prompt 

:KEYI KEY=F9 
HELP=retrieve 
ACTION=RETRIEVE. 

F9=Retrieve 

:KEYI KEY=F12 
HELP=cancel 
ACTION='CANCEL SET' 
VARUPD=NO. 

F12=Cancel 

:KEYI KEY=F24 
HELP=morekeys 
ACTION=MOREKEYS. 

F24=More keys 

:KEYI KEY=ENTER 
HELP=enter 
ACTION=ENTER. 

:KEYI KEY=HELP 
HELP=help 
ACTION=HELP. 

:KEYI KEY=HOME 
HELP=home 
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ACTION=HOME. 
:KEYI KEY=PAGEDOWN 
HELP=pagedown 
ACTION=PAGEDOWN. 
:KEYI KEY=PAGEUP 
HELP=pageup 
ACTION=PAGEUP. 
:KEYI KEY=PRINT 
HELP=print 
ACTION=PRINT. 


: PANEL NAME=xmpmenu 
HELP='menu/help' 
KEYL=menukeys 
ENTER='MSG CPD9817 QCPFMSG' 
PANELID=ZMENU 
TOPSEP=SYSNAM, 

Example Menu 


oe, 

Ko eee eee eee ee ee 
.* Define the menu area 

KO eee eee eee ee ee 
:MENU DEPTH='*' 


SCROLL=NO 
BOTSEP=SPACE. 
:TOPINST.Select one of the following: [J 


:MENUI  OPTION=1 fy 
ACTION='CMD ?t0OQ11cm2' 
HELP='menu/option1'. 

Work with members in a file 

x 

:MENUI OPTION=2 
ACTION='CMD ?t0Q11cm3' 
HELP='menu/option2'. 

Work with record definitions 


.* Use a command line and allow commands and option numbers 

eK ee er 

:CMDLINE SIZE=LONG. [J 

Selection or command 

x 

:EPANEL. 

ee 

x 

eR eee 
.* Define help modules for the menu panel 

eR eee 
:HELP NAME=key1. 

Function Keys - Help 

:XH3.Function keys 

:EHELP. 

Pa 


sHELP NAME=helpf1. 
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:PARML. 

:PT.F1=Help 

:PD. 

Provides additional information about using the display or a 
specific field on the display. 

: EPARML. 

:EHELP. 

gok 

:HELP NAME=exit. 

:PARML. 

:PT.F3=Exit 

:PD. 

Ends the current task and returns to the display from which the 
task was started. 

: EPARML. 

:EHELP. 

aX 

:HELP NAME=prompt. 

:PARML. 

:PT.F4=Prompt 

:PD. 

Provides assistance in entering or selecting a command. 
: EPARML. 

:EHELP. 

ie 

:HELP NAME=retrieve. 

:PARML. 

:PT.F9=Retrieve 

:PD. 

Displays the last command you entered on the command line and 
any parameters you included. Pressing this key once, shows the 
last command you ran. Pressing this key twice, shows the 
command you ran before that and so on. 

: EPARML. 

:EHELP. 

Ps 

:HELP NAME=cancel. 

:PARML. 

:PT.F12=Cancel 

:PD. 

Returns to the previous menu or display. 

: EPARML. 

:EHELP. 

x 

:HELP NAME=morekeys. 

:PARML. 

:PT.F24=More keys 

:PD. 

Shows additional function keys. 

: EPARML. 

:EHELP. 

x 

:HELP NAME=enter. 

:PARML. 

:PT. Enter 

:PD. 

Submits information on the display for processing. 

: EPARML. 

:EHELP. 

x 


sHELP NAME=help. 
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Provides additional information about using the display. 

: EPARML. 

:EHELP. 

x 

:HELP NAME=home. 

:PARML. 

:PT.Home 

:PD. 

Goes to the menu that was shown after you signed on the system. 
This menu is either the initial menu defined in your user 
profile or the menu you requested from the Sign-On display. 
: EPARML. 

:EHELP. 

x 

:HELP NAME=pagedown. 

:PARML. 

:PT.Page Down (Roll Up) 

:PD. 

Moves forward to show additional information for this display. 
: EPARML. 

:EHELP. 

aX 

:HELP NAME=pageup. 

:PARML. 

:PT.Page Up (Roll Down) 

:PD. 

Moves backward to show additional information for this display. 
: EPARML. 

:EHELP. 

x 

:HELP NAME=print. 

:PARML. 

:PT.Print 

:PD. 

Prints information currently shown on the display. 

: EPARML. 

:EHELP. 

BE 

:HELP NAME='menu/help'. 

Example Menu - Help 


“Ps 

The Example Menu shows an example of a menu created using the UIM. 
:XH3. 

How to Use a Menu 

=P, 

To select a menu option, type the option number and press Enter. 
Ps 


To run a command, type the command and press Enter. For assistance 
in selecting a command, press F4 (Prompt) without typing anything. 
For assistance in entering a command, type the command and press F4 
(Prompt). To see a previous command you entered, press F9 
(Retrieve). 

oPx 

To go to another menu, use the Go to Menu (GO) command. Type GO 
followed by the menu ID, then press the Enter key. For example, to 
go to the User Tasks (USER) menu, type GO USER and press the Enter 
key. The menu ID is shown in the upper left corner of the menu. 
For assistance in entering the GO command, type GO and press F4 
(Prompt). If you do not know the entire menu name you can use a 
generic name. For example, GO US* will show a list of all menus 
that start with US. 

:EHELP. 


* 


: HELP NAME='menu/option1'. 
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Option 1 - Help 

:XH3.Option 1. Work with members in a file 

+P 

Select this option to work with the members in a file. You will be 
prompted for the name of the file. 

:EHELP. 

.* 

:HELP NAME='menu/option2'. 

Option 2 - Help 

:XH3.Option 2. Work with record definitions 

Ps 

Select this option to work with record definitions for a file. 
You will be prompted for the name of the file. 

:EHELP. 


:EPNLGRP. 


Defining a Panel Group Object Using UIM 


Using the UIM, you can create a panel group object. The panel group object can 
contain the definitions for dialog variables, lists, panels and help modules. To 
create a panel group object, do the following. 


1. Create a member in a source physical file. 


2. Enter the UIM tag source to describe the panel group using a source editor 
such as the Source Entry Utility (SEU). An example panel group exists in 
member T0011PN2 in file QATTUIM in library QUSRTOOL. You can copy this 
example to use as a template to create your own panel group. 


3. Use the Create Panel Group (CRTPNLGRP) command to create the panel 
group object using the tag source as input. Here is an example of using the 
CRTIPNLGRP command. 


CRTPNLRP PNLGRP(MYLIB/MYPNLGRP) SRCFILE(MYLIB/QPNLSRC) 


The source member defaults to the name of the panel group being created. 


Creating a List Panel 


Any of the "Work with..." panels are list panels. In this example, the Work with File 
Members panel is used. Defining the list panel is similar to defining a subfile in 
DDS, but the UIM determines the appearance of the panel. 


The panel shown in Figure 16-3 on page 16-14 shows an example of a mixed 
panel with a list area. The panel is mixed because it contains two types of areas: a 
data presentation area at the top and a list area at the bottom. 


The data presentation area at the top consists of the fields which identify the file 
and library name. The list area begins with the instruction line, Type options, press 
Enter and ends with the scroll information (More...). 

In this example, the panel contains a special type of list area called an action list. 
An action list is a list which contains an option column. The user types in allowed 
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option numbers to perform actions against the object represented by the entry in 
the list. If you need more information on creating list panel help, see “Help in a List 
Area” on page 19-5. 


Work with File Members 
BAVC) cvs yotdeh Seah Abas XXXXXXXXXX F4 for list 
Library ...... XXXXXXXXXX library, *CURLIB, *LIBL 


Type options, press Enter. 
3=Copy 4=Remove 5=Display 7=Reorganize 8=Member description 4 | 
9=Clear 


Opt Member Type Text fj 


XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXXXXXKXXXAXAKAKXXAXAXAKKXAXAAKAK 
XXXXXXXXXX  XXXXXXXXXX — XXXXXXXXXXXXXXXXXXXXXXKXXXAXAXAKXXAXAXAKKXAXAAKAKK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXXXXXKXXXAXAXAXXXAXAKAKKXAXAAKAK 
XXXXXXXXXX  XXXXXXXXXX_  XXXXXXXXXXXXAXXXXXXXXXXKXXXAAXAXAKXXAXAKAKAXAXAAKAK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXXXXXKXXXXXAXAKXXAXAKAKKXAXAAKAK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXXXAXKXXXAXAXAKXXAXAKAAKKXAXAAKAK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXXXXXKXXXAXAXAKXXAXAXAKKXAXAAKAK 
XXXXXXXXXX — XXXXXXXXXX Se Eee eee ae 
a More... 
Parameters for options 3 and 5 or command [J 
===> 


F3=Exit F4=Prompt F9=Retrieve F1l=Display names only  F12=Cancel 9 | 


Figure 16-3. Example List Panel 


The panel shown in Figure 16-4 is an alternate view shown when the user presses 
F11 (Display names only) on the panel shown in Figure 16-3. The alternate view 
shown here uses a multiple-column layout. The panel is divided into four layout 
columns of equal size. The Opt and Member columns appear in each layout 
column. The alternate view shows four times as many list entries as the original 
view, but does not show the Type and Text columns for each entry. 


Work with File Members 


File vs Sra ete ee XXXXXXXXXX F4 for list 
Library ...... XXXXXXXXXX library, *CURLIB, *LIBL 
Type options, press Enter. 
3=Copy 4=Remove 5=Display 7=Reorganize 8=Member description 4 | 


9=Clear 

Opt Member Opt Member Opt Member Opt Member 5 | 
_ _ XXXXXXXXXX —_ _ XXXXXXXXXX _  XXXXXXXXXX _ _ XXXXXXXXXX 
— XXXXXXXXXX —_ XXXXXXXXXX _ XXXXXXXXXX — XXXXXXXXXX 
__-XXXXXXXXXX __-XXXXXXXXXX — _ XXXXXXXXXX __XXXXXXXXXX 
_  XXXXXXXXXX _ _ XXXXXXXXXX _  XXXXXXXXXX _ _ XXXXXXXXXX 
— XXXXXXXXXX —__ XXXXXXXXXX _ XXXXXXXXXX — XXXXXXXXXX 
—_-XXXXXXXXXX __-XXXXXXXXXX _ _XXXXXXXXXX __ XXXXXXXXXX 
—_ _ XXXXXXXXXX _ _ XXXXXXXXXX _  XXXXXXXXXX _ _ XXXXXXXXXX 
—_ XXXXXXXXXX —__ XXXXXXXXXX _ XXXXXXXXXX —__ XXXXXXXXXX 

XXXXXXXXXX XXXXXXXXXX XXXXXXXXXX —__-XXXXXXXXXX 


More... 
Parameters for options 3 and 5 or command [J 
===> 


F3=Exit F4=Prompt F9=Retrieve F1l=Display descriptions F12=Cancel of 


Figure 16-4. Example of Alternate View of List 
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The reference numbers in the example panel do not appear on the display. They 
are shown for illustration purposes and also appear in the UIM tag source shown in 
“Source for Example List Panel” on page 16-17. These reference numbers show 
which portions of the source define text and information which appears on the 
panel. 


2 


The panel title is defined as text following the period of the display panel 
(PANEL) tag. 


The text for the file and library name is defined as text following the period of 
the data item (DATAI) tag. The file name and library name are dialog variable 
values. Each dialog variable is defined using the variable definition (VAR) 
tag. The name of the dialog variable is specified on the VAR attribute of the 
DATAI tag. The possible choices text for each input field is defined as text 
following the period of the data item choices (DATAC) tag. 


The file name and library are formatted as a qualified object name because 
GRPSEP=QINDENT is specified on the data group (DATAGRP) tag which sur- 
rounds the two DATAI tags. 


The dialog variables for the file name and library name are defined using the 
VAR tags at —¥ and ff, respectively, shown on page 16-19. 


The instruction line is defined as text following the period of the top instruction 
(TOPINST) tag. 


Each list option is defined using the list action (LISTACT) tag. The text, 
including the option number with the equal sign, is defined as text following 
the period of the LISTACT tag. 


The column heading for each column is defined as text following the period of 
the list column (LISTCOL) tag. The VAR attribute of the LISTCOL tag identifies 
the name of the dialog variable whose value is displayed under the column 
heading. 


The dialog variable name specified, must be defined using the VAR tag. The 
dialog variable name must also be specified on the VARS attribute of the list 
definition (LISTDEF) tag for the list appearing in the panel. 


The dialog variables for the option, member name, member type, and 
description text are defined using the VAR tags at @, DJ], @, and @, 
respectively, shown on page 16-19. 


The names of these variables also appear in the VARS attribute of the 
LISTDEF tag at [J shown on page 16-21. The name of the list definition 
must be specified on the LISTDEF attribute of the list area (LIST) tag at JJ, 
shown on page 16-23. 


The extended action entry that appears immediately below the column 
headings is defined by specifying EXTACT=YES on the LIST tag. Each column 
which has an input field in the extended action entry must specify 
EXTACT=YES on the LISTCOL tag. 


The extended action entry allows the user to perform actions without having to 
scroll to a specific entry in the list. 


Each list option defined by the LISTACT tag, specifies whether the action is 
allowed to be performed against the extended action entry, the list entries 
appearing below the extended action entry, or both. This specification is 
made using the ACTFOR attribute of the LISTACT tag. 
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The scroll information, More... and Bottom, are shown because the list area is 
defined as scrollable because the SCROLL attribute defaults to YES on the 
LIST tag. 


EF] The command line is defined using the command line (CMDLINE) tag. The 
command line prompt text is defined as text following the period of the 
CMDLINE tag. The UIM automatically provides the arrow (===>) for every 
command line. 


The command line can be used to enter parameters for list options. Before 
processing list options, the UIM places the contents of the command line into 
a dialog variable. The dialog variable can be: 


¢ Substituted into a CL command specified as the action to perform on a 
LISTACT tag 


e Used by an exit program specified as the action to perform on the 
LISTACT tag 


e Used by the application program when it is performing the actions for the 
list 


The dialog variable used to contain parameters from the command line is 
defined using the VAR tag at iJ, shown on page 16-19. It is also specified 
on the PARMS attribute of the list area (LIST) tag at [J, shown on page 16-23. 
The UIM places the contents of the command line in the dialog variable speci- 
fied by the PARMS attribute before beginning list option processing. 


Then the dialog variable is used as a substitution variable in a command 
string on a LISTACT tag at [@J, shown on page 16-23. 


—]_ Each function key is defined using the key list (KEYL) tag. The text, including 
the function key name, is defined as text following the period of the KEYI tag. 


All function keys are defined by placing the KEYI tags between the key list 
(KEYL) and EKEYL tags. The name specified on the NAME attribute of the 
KEYL tag is also specified on the KEYL attribute of the PANEL tag. 


Some function keys, such as Enter, do not have text specified for the KEY| 
tag. In this case, no text appears on the display. However, all function keys 
must be defined using the KEY! tag so the UIM knows what action is 
assigned to each key and what help module to use when help is displayed for 
the function keys. 


Required Tags for a List Panel 


Figure 16-5 on page 16-17 shows the required tags for creating a UIM list panel. 
For an example of the required and optional tags, see “Source for Example List 
Panel” on page 16-17. 


Note: The tags in Figure 16-5 on page 16-17 require attributes. These attributes 
are not shown. Without these attributes, the example in Figure 16-5 on 
page 16-17 will not compile. For a description of the required attributes for 
these required tags, see Appendix A, “UIM Panel Group Definition 
Language.” 
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:PNLGRP. 
:CLASS. 
:ECLASS. = 
7 VAR. 


?KEYL. 
:KEYI. a 
:EKEYL. 

> PANEL. 
:LISTDEF. 


:LIST. 
:LISTACT. 
:LISTCOL. 
:LISTVIEW. 


SELIST. 
:EPANEL. 
:HELP. 


SEHELP. 
: EPNLGRP. 


Figure 16-5. Required UIM Tags for a List Panel 


Source for Example List Panel 


This is a partial listing of member T0011PN2 in source file QATTUIM in library 
QUSRTOOL. 


:PNLGRP =HLPSHELF=LIST 

DFTMSGF=t0011msgf2 

SUBMSGF=t0011msgf2. 
git 
.* The import tag specifies that all help is to be found 
.-* in panel group TQO11HL2 searching the library list. 
:IMPORT NAME='*' 

PNLGRP=t0O11h12. 


.* Option 
.* Note: Need WIDTH=1 to preserve column alignment on confirmation panel. 
: CLASS NAME=optcl 

BASETYPE='ACTION' 
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.* Object name 

: CLASS NAME=namec]l 
BASETYPE='OBJNAME 10'. 

:ECLASS. 


.* Library name 

: CLASS NAME=1ibcl 
BASETYPE='OBJNAME 10'. 

=TLs 

:TI VALUE='"*LIBL"'.*LIBL 

:TI VALUE='"*CURLIB"'.*CURLIB 

SEP 

:ECLASS. 


.* File attribute 

:CLASS NAME=attrcl 
BASETYPE='CHAR 10' 
CASE=UPPER. 

:ECLASS. 


.* Descriptive text 

: CLASS NAME=textcl 
BASETYPE='IGC 50' 
SUBST=QUOTED. 

:ECLASS. 


-* Source type 

: CLASS NAME=srctypcl 
BASETYPE='CHAR 10'. 

:ECLASS. 


Additional CLASS tags in member TOQ11PN2 are not shown here 


.* Command line parameters 

: CLASS NAME=parmc 
BASETYPE='CHAR 255'. 

sECLASS. 


.* Exit program specification for CALL dialog command 
: CLASS NAME=exitcl 

BASETYPE='CHAR 20'. 
:ECLASS. 


.* View number 

:CLASS NAME=vwnumc 1 
BASETYPE='BIN 15'. 

:ECLASS. 


.* Classes for pad variables in variable record definitions. 
: CLASS NAME=padicl 
BASETYPE='CHAR 1'. 
sECLASS. 
: CLASS NAME=pad2cl 
BASETYPE='CHAR 2'. 
:ECLASS. 
: CLASS NAME=pad10cl 
BASETYPE='CHAR 10'. 
:ECLASS. 
: CLASS NAME=pad13cl 
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BASETYPE='CHAR 13'. 
:ECLASS. 
: CLASS NAME=pad48cl 
BASETYPE='CHAR 48'. 
:ECLASS. 
: CLASS NAME=pad50cl 
BASETYPE='CHAR 50'. 


:ECLASS. 
x 
eR ee 
.* Define all dialog variables 
eR ee 
x 
eK pee ee 
.* Variables for file and library 
eK eer re ee 
i 
.* File name 
:VAR NAME=file [Ly 
CLASS=namecl. 
i 
.* Library name 
:VAR NAME=lib [J 
CLASS=libcl. 
i 
.* attributes 
: VAR NAME=fattr 
CLASS=attrcl. 
i 
x 
eK pee ee ee 
.* Variables for list of members 
eK peer ee 
i 
.* option for list of members 
:VAR NAME=mopt 
CLASS=optcl. 
i 
.* Object name 
:VAR NAME=mbr [J 
CLASS=namecl. 
i 
.* member type 
:VAR NAME=mtype [fj 
CLASS=attrcl. 
i 
.* Descriptive text 
:VAR NAME=mtext [J 


CLASS=textcl. 


Additional VAR tags in member TQ011PN2 are not shown here 


oe 
eK per ee ee 
.* Variable for command line parameters 
eK pee ee ee 
i 
.* Command line parameters 
:VAR NAME=parms [fq 

CLASS=parmcl. 
4% 
eK pee ee 
.* Variables for specifying CALL/exit programs 
eK eer er ee 
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aK eee eee eee eee 
-* Program to call for all UIM exits 
:VAR NAME=exitpgm 

CLASS=exitcl. 


.* View number for list of members 
:VAR NAME=mbrvi ew 
CLASS=vwnumcl . 


Additional VAR tags in member TQOQ11PN2 are not shown here 


Variables for padding in variable record definitions. 
Padding is needed in variable records so the layout 

of the record matches a list format returned from 

an API. The pad variables are used as placeholders for 
variables not used in the API format or for reserved space 
in the API format. 


eK per rr 
: VAR NAME=pad1 
CLASS=padicl. 
: VAR NAME=pad2 
CLASS=pad2cl. 
:VAR NAME=pad10 
CLASS=padl0cl. 
: VAR NAME=pad13 
CLASS=pad13cl. 
:VAR NAME=pad48 
CLASS=pad48cl. 
:VAR NAME=pad50 
CLASS=pad50cl. 
x 
eR eee 
.* Define a variable record for file, library and file attribute 
eR ee 


:VARRCD NAME=filelib 
VARS='file lib fattr' 
NOGET='fattr' 


:VARRCD NAME=exitprog 
VARS='exitpgm' 


x 

eR er 
.* Define a variable record for list of members. 

.* The layout of this record is designed to match the 


.* List Database File Members API (QUSLMBR) format name MBRLO200. 
:VARRCD NAME=mbr10200 
VARS='mbr mtype pad13 pad13 mtext' 


NOPUT='pad13' 
NOGET='mtype pad13 mtext' 


Additional VARRCD tags in member TQQ11PN2 are not shown here 
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* 
* 
Ke ane ee a ee 


.* Define a list of members 


:LISTDEF NAME=mbrlist 
VARS='mopt mbr mtype mtext' 
MSGID=USRO101. 


Additional LISTDEF tags in member TQ011PN2 are not shown here 


.* Condition for physical files 
: COND NAME=pf 
EXPR='fattr="PF her 


-* Conditions for views of members list 

: COND NAME=mbrviewl 
EXPR='mbrview=0'. 

:COND NAME=mbrview2 
EXPR='mbrview=1'. 


Additional COND tags in member TO011PN2 are not shown here 


x 
KR ee eee 
.* Define truth table to specify that mbrviewl and mbrview2 
-* are mutually exclusive conditions 
.* This will cause UIM to reserve only one line of function 
.* keys on the work with members panel 
eR eee 
:TT NAME=mbrtt 
CONDS='mbrviewl mbrview2'. 
: TTROW VALUES=' 1 Q °°. 
: TTROW VALUES=' 0 1 vs 
:ETT. 


Additional TT tags in member T0Q11PN2 are not shown here 


All MBAR tags in member TOQ11PN2 are not shown here 


x 
Lets 
Rr ere 
.* Define keys for work with members panel 
eR eee 
:KEYL NAME=mbrkeys [J 
HELP=keyl. 
:KEYI KEY=F1 


HELP=helpf1 
ACTION=HELP. 
:KEYI KEY=F3 


HELP=exit 
ACTION='EXIT SET' 
VARUPD=NO. 
F3=Exit 
:KEYI KEY=F4 
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HELP=prompt 
ACTION=PROMPT 
PRIORITY=30. 

F4=Prompt 

:KEYI KEY=F9 
HELP=retrieve 
ACTION=RETRIEVE 
PRIORITY=35. 

F9=Retrieve 

:KEYI KEY=F11 
HELP=mbrviewname 
ACTION=CHGVIEW 
PRIORITY=25 
COND=mbrviewl. 

F1ll=Display names only 

:KEYI KEY=F11 
HELP=mbrviewdesc 
ACTION=CHGVIEW 
PRIORITY=25 
COND=mbrview2. 

Fll=Display descriptions 

:KEYI KEY=F12 
HELP=cancel 
ACTION='CANCEL SET' 
VARUPD=NO. 

F12=Cancel 

:KEYI KEY=F24 
HELP=morekeys 
ACTION=MOREKEYS. 

F24=More keys 

:KEYI KEY=ENTER 
HELP=enter 
ACTION=ENTER. 

:KEYI KEY=HELP 
HELP=help 
ACTION=HELP. 

:KEYI KEY=PAGEDOWN 
HELP=pagedown 
ACTION=PAGEDOWN. 

:KEYI KEY=PAGEUP 
HELP=pageup 
ACTION=PAGEUP. 

:KEYI KEY=PRINT 
HELP=print 
ACTION=PRINT. 


sEKEYL. 


Additional KEYL tags in member TO011PN2 are not shown here 


> PANEL NAME=wrkmbr 
HELP='wrkmbr/' 
KEYL=mbrkeys [EJ 
TT=mbrtt 
ENTER='RETURN 500' 
TOPSEP=SPACE. 

Work with File Members [fq 


ee 


.* Define a data presentation area to display the 
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.* library/file name whose members are listed. 


:DATA DEPTH=3 
SCROLL=NO 
LAYOUT=1 
BOTSEP=SPACE 
COMPACT 


.* Divide the layout width into two columns. 

.* The first column is for the prompt text with leader dots. 
.* The second column is for the variable values. 

:DATACOL WIDTH=22. 

:DATACOL WIDTH=12. 

:DATACOL WIDTH='*'. 


.* Display qualified file name 

:DATAGRP GRPSEP=QINDENT 
HELP='wrkmbr/filelib' 
COMPACT 


:DATAI VAR=file 
USAGE=INOUT 
PROMPT='CALL exitpgm' 


File 

:DATAC.F4 for list 

:DATAI VAR=1ib 
USAGE=INOUT 


Library 
:DATAC. library, *CURLIB, *LIBL 
: EDATAGRP. 


LIST DEPTH='x'! 
LISTDEF=mbrlist [J 
ACTOR=UIM 
EXTACT=YES [jj 
MAXHEAD=4 
MAXACTL=3 
VIEW=mbrview 
PARMS=parms 
BOTSEP=SPACE. 
:TOPINST.Type options, press Enter. 


:LISTACT OPTION=3 
ACTFOR=BOTH [J 
NOCMD=PROMPT 
NOEXT=PROMPT 
HELP='wrkmbr/cpyf ' 
ENTER='CMD CPYF ?*FROMFILE(&lib./&file.) ' 
ENTER=' ?*FROMMBR(&mbr.) &parms.' [@ 
PROMPT='CMD ?CPYF ?*FROMFILE(&lib./&file.) ' 
PROMPT=' ?*FROMMBR(&mbr.) &parms.' [@ 
EXTENTER='CMD ?CPYF ?*FROMFILE(&lib./&file.)' 
EXTENTER=' ??FROMMBR(&mbr.) &parms.' [@ 
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EXTPROMPT='CMD ?CPYF ?*FROMFILE(&lib./&file.)' 
EXTPROMPT=' ??FROMMBR(&mbr.) &parms.'. K | 
3=Copy 
x 
:LISTACT OPTION=4 
ACTFOR=LISTE 
HELP='wrkmbr/rmvm' 
ENTER='CMD RMVM FILE(&lib./&file.) MBR(&mbr.) ! 
PROMPT='CMD ?RMVM 2*FILE(&lib./&file.) 2*MBR(&mbr.)' 
USREXIT='CALL exitpgm'. 
4=Remove 
x 
:LISTACT OPTION=5 
COND=pf 
ACTFOR=BOTH 
NOEXT=PROMPT 
HELP='wrkmbr/dsppfm' 
ENTER='CMD DSPPFM FILE(&lib./&file.) MBR(&mbr.) &parms. ' 
PROMPT='CMD DSPPFM ?*FILE(&lib./&file.) ?*MBR(&mbr.) &parms.' 
EXTPROMPT='CMD DSPPFM ?*FILE(&lib./&file.) ?2MBR(&mbr.) &parms. 
5=Display 
x 
:LISTACT OPTION=7 
COND=pf 
ACTFOR=BOTH 
HELP='wrkmbr/rgzm' 
ENTER='CMD RGZPFM FILE(&lib./&file.) MBR(&mbr.) ' 
PROMPT='CMD ?RGZPFM ?*FILE(&lib./&file.) ?*MBR(&mbr.)'. 
7=Reorganize 
x 
:LISTACT OPTION=8 
ACTFOR=BOTH 
HELP='wrkmbr/dspfd' 
ENTER='CALL exitpgm' 
PROMPT='CALL exitpgm'. 
8=Member description 
* 
:LISTACT OPTION=9 
COND=pf 
ACTFOR=LISTE 
HELP='wrkmbr/clrm' 
ENTER='CMD CLRPFM FILE(&lib./&file.) MBR(&mbr.) ' 
PROMPT='CMD ?CLRPFM ?*FILE(&lib./&file.) ?*MBR(&mbr.)'. 


.* Define the columns and headings to display 
eK per er ee 
:LISTCOL VAR=mopt 

USAGE=INOUT 

EXTACT=YES [jj 

HELP='wrkmbr/option' 


MAXWIDTH=6. 

Opt 

:LISTCOL VAR=mbr 
USAGE=OUT 
EXTACT=YES 
HELP='wrkmbr/mbr' 
MAXWIDTH=10. 

Member 

:LISTCOL VAR=mtype 


USAGE=OUT 
HELP='wrkmbr/type' 
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MAXWIDTH=10. 


Type 

:LISTCOL VAR=mtext 
USAGE=OUT 
HELP='wrkmbr/text' 
MAXWIDTH='*'. 

Text 


Rowe esssestestetess See eo secee ls ssc 
.* Define multiple views for F1l to toggle between 


:LISTVIEW COLS='mopt mbr mtype mtext'. 
s:LISTVIEW COLS='mopt mbr' layout=4. 


:CMDLINE SIZE=SHORT. fy 
Parameters for options 3 and 5 or command 
w* 


:EPANEL. 
Additional PANEL tags in member TQ011PN2 are not shown here 


* 
KK ane eee -- -  - -- 


.* End of panel group source 
KR ww ww we ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 


:EPNLGRP. 


Application Programming for a List Panel 


An example of an application program to display the list panel shown in 

Figure 16-3 on page 16-14 can be found in member T0011CP2 in source file 
QATTSYSC in library QUSRTOOL. This is an ILE C program which calls the 
appropriate UIM application programming interfaces (APIs) to display the panel. 


A general example of an RPG application using the UIM APIs can be found in 
QUSRTOOL. Refer to member T0011INF in source file QATTINFO in library 
QUSRTOOL. See Chapter 21, “Designing IBM AS/400-Style Displays” on 
page 21-1 for more information on using the examples. 


To write a program in any language to display the example list panel, the program 
should do the following: 


1. Call the Open Display Application (QUIOPNDA) API to open the panel group. 
The panel group must already be created using the Create Panel Group 
(CRTPNLGRP) command. 


2. Set up a buffer containing the values for the following dialog variables: 
FILE A CHAR 10 variable which is the name of the file. 


LIB A CHAR 10 variable which is the name of the library where the file 
resides. 


FATTR A CHAR 10 variable which is the file attribute of the file. This variable 
is used to condition on list options which are only allowed for physical 
files. 
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3. Call the Put Dialog Variable (QUIPUTV) API to change the contents of the 
dialog variables using variable record FILELIB and the buffer initialized in the 
previous step. 


4. Set up a buffer containing a value for the following dialog variable: 


EXITPGM A CHAR 20 variable which identifies the program to be called as a 
UIM exit program. For extended program model (EPM) languages, 
this BASETYPE attribute of the CLASS tag used to define the 
EXITPGM dialog variable must be changed to a CHAR 130 dialog 
variable. 


For information on how this dialog variable must be set, see the 
description of the CALL dialog command in Appendix B, “UIM 
Dialog Commands” on page B-1. 


5. Call the Put Dialog Variable (QUIPUTV) API to change the contents of the 
dialog variable using variable record EXITPROG and the buffer initialized in the 
previous step. 


6. Create a user space that will receive a list of members in a file using the 
Create User Space (QUSCRTUS) API. The members in a file are retrieved 
using the List Database File Members (QUSLMBR) API. If the application pro- 
gramming language supports pointers, use the Retrieve Pointer to User Space 
(QUSPTRUS) API to obtain a pointer to the contents of the user space. This 
lets the application program directly manipulate the data. Otherwise, use the 
Retrieve User Space (QUSRTVUS) API to obtain the contents of the user 
space. For a description of these APIs, see the System API Reference. 


7. For every member in the file to be displayed, do the following. A list of the 
members in a file can be retrieved using the List Database File Members 
(QUSLMBR) API. For a description of this API, see “List Database File 
Members (QUSLMBR) API” in System API Reference. 


a. Set up a buffer containing values for the following dialog variables: 
MBR A CHAR 10 variable which is the member name. 
MTYPE A CHAR 10 variable which is the member type. 

PAD13 A CHAR 13 reserved space in the buffer. 
PAD13 A CHAR 13 reserved space in the buffer. 


MTEXT A CHAR 50 variable which is the descriptive text for the 
member. 


Note: The layout of this buffer is designed to match the layout of the 
entries in the user space returned by the QUSLMBR API using the 
MBRLO200 format. Therefore, instead of setting up a buffer, the 
application program can pass the buffer as it exists in the user 
space. 

The two PAD13 variables are used to tell the UIM to ignore two 
variables in the MBRLO200 format returned by the QUSLMBR API. 


The variables are the creation date and time and the last source 
change data and time. 


b. Call the Add List Entry (QUIADDLE) API to add a list entry to the list 
named MBRLIST using variable record MBRLO200 and the buffer initialized 
in the previous step. 
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8. Call the Display Panel (QUIDSPP) API to display panel WRKMBR. The UIM 
returns control to the application when one of the following occurs: 


e The user presses the Enter key without typing any list options or a 


command on the command line. The program variable passed as the func- 
tion requested parameter to the QUIDSPP API is set to 500. This is done 
because ENTER='RETURN 500' is specified on the PANEL tag which defines 
the WRKMBR panel. 


The user presses the F12 (Cancel) key. The program variable passed as 
the function requested parameter to the QUIDSPP API is set to -8. This is 
the value defined for the CANCEL dialog command. 


The user presses the F3 (Exit) key. The program variable passed as the 
function requested parameter to the QUIDSPP API is set to -4. This is the 
value defined for the CANCEL dialog command. 


9. Call the Close Application (QUICLOA) API to close the UIM application. This 
frees up the system resources used by the UIM application. 


Creating a Confirmation List Panel 


Options on an action list panel that perform destructive operations should use a 
confirmation panel to allow the user to confirm or cancel the request before it is 
performed. A confirmation panel should be provided for actions such as 4=Remove 
and 9=Clear shown in the example panel in Figure 16-3 on page 16-14. 


An example of a confirmation panel is shown in Figure 16-6. This confirmation 
panel is used when the user types option 4 on the panel shown in Figure 16-3 on 


page 16-14. 
(— = 
Confirm Remove of Members 
File... .. . . ~:~ XXXXXXXXXX 
Library .....32 XXXXXXXXXX 


0 


ot 


SPHHHHHH HHH HH 


Press Enter to confirm your choices for 4=Remove. 
Press Fl2 to return to change your choices. 


Fll=Display names only  F12=Cancel 


Member Type Text 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXXAXXKAXKAAAKAXKAKAAKKKAKAAAKA KKK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXXAXXKAXKAAARKAXAAKAAKKAAKKAAKA KKK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXKAXXKAXKAARKAXAXKAAKKAAKKAAKA KKK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXAXXXAXXKAXKAAXKAXAAKAAKKAAKAAAKA KKK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXKAXXKAXKAAXKAXAAKAAKKAAKKAKKA KKK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXAXXXAXXKAXKAAXKAXKAKAAKKAAKKAAKA KKK 
XXXXXXXXXX_  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXXAXXKAXKAAXKAXAAKAAKKAAKAKAAKA KKK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXKAXXKAXKKAXKAXAKAARKAAKAKAAKA KKK 
XXXXXXXXXX_  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXXAXXKAXKKAXKAX AKA AKKA AKA KAKA KKK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXAXXKAXXKAXKAAARKAXAKAAKKKAKKAAKA KKK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXXXXAAXXKAXKAAXKAXAAKAAKKAAKKAAKA KKK 
XXXXXXXXXX  XXXXXXXXXX  XXXXXXXXXXXXXXXAXXXAXXKAXKKAXKAXAAKAAKKAAKKAAKA KKK 
More... 


Figure 16-6. Example Confirmation List Panel 


The confirmation panel appears similar to the action list panel with the following 
exceptions: 


e The instructions tell the user to confirm or cancel the option. 
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e The displayed list is for output only. The user cannot change any of the option 
numbers. 


e The F3 (Exit) key is not allowed from a confirmation panel. 


e There is no command line on a confirmation panel. 


When the user presses the F11 key to change to a different view, the view of the 
action list panel is changed when it is redisplayed. This is done because the same 
dialog variable is specified on the VIEW attribute of the LIST tag for both the action 
list panel and the confirmation panel. 


Required Tags for a Confirmation List Panel 


The required tags for a confirmation list panel are basically the same as those 
required for a list panel which are described in Figure 16-5 on page 16-17. 
However, the LISTACT tag is not required. 


Source for Example Confirmation Panel 


To define this confirmation panel, additional source needs to be added to the 
source shown in “Source for Example List Panel” on page 16-17. The following 
are excepts from member T0011PN2 in source file QATTUIM in library 
QUSRTOOL. First, a new list definition needs to be made. This list definition con- 
tains a copy of the list entries being confirmed. The confirmation list contains the 
same dialog variables as are contained in the list of members. The following list 
definition (LISTDEF) tag should be placed after the LISTDEF tag at [J], shown on 
page 16-21. 

x 

K eae ee eee eee ee eee eee eee eee ee ee ee eee eee ee ee ee eee ee eee eee eee 


.* Define a list of members for confirmation panels 
K eee eee ee eee ee ee eee eee ee eee eee ee eee ee ee eee ee eee ee eee eee eee eee 


:LISTDEF NAME=mbrconf 
VARS='mopt mbr mtype mtext'. 


Next, function keys need to be defined for the confirmation panel. Confirmation 
panels should not allow F3 (Exit). The following key list (KEYL) tag should be 
placed after the KEYL tag, shown in “Source for Example List Panel” on 


page 16-17. 
x 
eR ee a ee eee eee 
.* Define keys for confirm remove of members 
eR ee eee 
:KEYL NAME=mconf keys 
HELP=keyl. 
:KEYI KEY=F1 


HELP=helpf1 
ACTION=HELP. 
:KEYI KEY=F11 
HELP=altview 
ACTION=CHGVIEW 
COND=mbrviewl. 
F11=Display names only 
:KEYI KEY=F11 
HELP=altview 
ACTION=CHGVIEW 
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COND=mbrview2. 
F1l=Display descriptions 
:KEYI KEY=F12 

HELP=cancel 

ACTION='CANCEL SET' 

VARUPD=NO. 
F12=Cancel 
:KEYI KEY=F24 

HELP=morekeys 

ACTION=MOREKEYS. 
F24=More keys 
:KEYI KEY=ENTER 

HELP=enter 

ACTION=ENTER. 
:KEYI KEY=HELP 

HELP=help 

ACTION=HELP. 
:KEYI KEY=PAGEDOWN 

HELP=pagedown 

ACTION=PAGEDOWN. 
:KEYI KEY=PAGEUP 

HELP=pageup 

ACTION=PAGEUP. 
:KEYI KEY=PRINT 

HELP=print 

ACTION=PRINT. 
:EKEYL. 


The confirmation panel needs to be defined. The following source should be 
placed after the EPANEL tag, shown in “Source for Example List Panel” on 
page 16-17. 


ig 
aK eee eee ee ee eee 
.* Define panel for confirm remove of members from WRKMBR panel 


: PANEL NAME=confrmvm 
HELP='confrmvm/' 
KEYL=mconfkeys 
TT=mbrtt 
ENTER='RETURN 100' 
TOPSEP=space. 
Confirm Remove of Members 
joe 
eK peer ee 
.* Define a data presentation area to display the 
.* library/file name whose members are listed. 


:DATA DEPTH=3 
SCROLL=NO 
LAYOUT=1 
BOTSEP=SPACE 
COMPACT 


.* Divide the layout width into two columns. 

-* The first column is for the prompt text with leader dots. 
.* The second column is for the variable values. 

:DATACOL WIDTH=22. 

:DATACOL WIDTH='*'. 
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.* Display qualified file name 
:DATAGRP GRPSEP=QINDENT 
HELP='wrkmbr/filelib' 


COMPACT 
:DATAI VAR=file 
USAGE=OUT 
File 
:DATAI VAR=1ib 
USAGE=OUT 
Library 
: EDATAGRP. 
x 
:EDATA. 
x 
eK per er 
.* Define the list area 
eK per er ee 
:LIST DEPTH='*' 
MAXHEAD=4 


LISTDEF=mbrconf 

VIEW=mbrview. 
:TOPINST.Press Enter to confirm your choices for 4=Remove. 
:TOPINST.Press F12 to return to change your choices. 


x 
eK per ee ee 
.* Define the columns of the list 
eK per re ee 
:LISTCOL VAR=mopt 
USAGE=OUT 
HELP='confrmvm/option' 
MAXWIDTH=6. 
Opt 
:LISTCOL VAR=mbr 
USAGE=OUT 
HELP='wrkmbr/mbr'' 
MAXWIDTH=10. 
Member 
:LISTCOL VAR=mtype 
USAGE=OUT 
HELP='wrkmbr/type' 
MAXWIDTH=10. 
Type 
:LISTCOL VAR=mtext 
USAGE=OUT 
HELP='wrkmbr/text ' 
MAXWIDTH='*'. 
Text 
x 
eK per er ee 
.* Define multiple views for F1l to toggle between 
eK peer ee 


:LISTVIEW COLS='mopt mbr mtype mtext'. 
:LISTVIEW COLS='mopt mbr' layout=4. 

x 

:ELIST. 

:EPANEL. 
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Automatic Confirmation Processing 
The UIM provides support to automatically perform confirmation processing. This 
support is available when the UIM is in control of processing list options by speci- 
fying ACTOR=UIM on the LIST tag that defines the action list. 


To have the UIM perform confirmation processing for a list option, specify the name 
of the confirmation panel on the CONFIRM attribute of the list action (LISTACT) tag 
that defines the option to be confirmed. The following UIM source shows the 
LISTACT tag for option 4 with the CONFIRM attribute specifying the name of the con- 
firmation panel. 


x 

:LISTACT OPTION=4 
ACTFOR=LISTE 
HELP='wrkmbr/rmvm' 
CONFIRM=confrmvm 
ENTER='CMD RMVM FILE(&lib./&file.) MBR(&mbr.)' 
PROMPT='CMD ?RMVM ?*FILE(&lib./&file.) ?*MBR(&mbr.) ' 
USREXIT='CALL exitpgm'. 

4=Remove 

uk 


For more information about defining a confirmation panel using the CONFIRM attri- 
bute, see “LISTACT (List Action)” on page A-90. 


When the UIM processes list options and finds an option with the CONFIRM attribute 
specified, the UIM does the following: 


1. Deletes the list specified on the LISTDEF attribute of the LIST tag in the confir- 
mation panel. 


2. Finds all entries in the action list with an option number the same as the option 
number being confirmed, and copies these entries to the confirmation list. 


3. Displays the confirmation panel. 


4. Remembers that the option number has been confirmed by the user if the user 
presses the Enter key. The confirmed options are processed in the order they 
appear in the action list. No further confirmation processing is done for this 
option number until the user types the option number for additional entries in 
the action list. 


5. Stops processing list options, if the user presses the F12 (Cancel) key, and 
redisplays the action list panel showing the first entry with the option number 
that was not confirmed. 


Application Programming for Confirmation Processing 
When ACTOR=UIM is specified on the LIST tag in the action list panel, there is no 
application programming needed because the UIM performs all confirmation pro- 
cessing. 


When ACTOR=CALLER is specified on the LIST tag in the action list panel, the appli- 
cation program that processes the list options should perform confirmation pro- 
cessing similar to the UIM processing as described in “Automatic Confirmation 
Processing.” 
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Creating a Data Presentation Panel 


Data presentation panels are used to display user data or allow input of user data 
in connection with an option on a list panel. When data input/output is scrollable 
and low in frequency and volume, UIM simplifies creating consistent data presenta- 
tion panels. 


The following shows the coding to create the Display Member Description display 
from the Work with File Members display. 


The panel shown in Figure 16-7 shows an example of a data presentation panel. 
This panel is shown as a result of using option 5 on the panel shown in 
Figure 16-3 on page 16-14. 


This panel contains two data presentation areas. The first area is using a vertical 
layout with two layout columns. This area shows the file, library, and member 
name. The second area also uses a vertical layout, but only one layout column. 
This area shows the detail information for the member identified in the first area. If 
you need more information on creating help for a data presentation panel, see 
“Help in a Data Area” on page 19-9. 


(— = 
Display Member Description 
File... ... . 6: XXXXXXXXXX Member... . ~~. :  XXXXXXXXXX fq 
Library .....3: XXXXXXXXXX 
Type of file ..........: PF 
Remote file. .........+.: ~ 4xNO 
Allow ODP sharing. .......: Yes 
Source type... . 2... 6 ee «© 3 ~~ XXXXXXXXXX 
Last source change date and time : 11/11/11 11:11:11 
Creation date and time .....: 11/11/11 11:11:11 
Change date and time ......: 11/11/11 11:11:11 
Number of records ........: 111111111 
Deleted records .........: 111111111 
Data space size. ........: 111111111 
Access path size ........: 111111111 
Ed More... 
F3=Exit F12=Cancel [ij 


— — 


Figure 16-7. Example Data Presentation Panel 


The second area is defined as a scrollable area because there are more items to 
show than will fit on a display at one time. The UIM automatically handles scrolling 
when the user presses the Page Up (Rolldown) or Page Down (Rollup) keys. 
When the Page Down operation is performed, the contents of the second data 
presentation area is replaced with the next set of items to show. This results in the 
panel shown in Figure 16-8 on page 16-33. 


Notice that the contents of the first area remain the same when the second area is 
scrolled. The scroll operation only applies to one area of the panel based on the 
location of the cursor. Also, because the first area is not defined as scrollable, the 
scroll operation does not apply to that area even when the cursor position is within 
the area. 
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(— a 
Display Member Description 
FIGs 22% 208 Boe ot XXXXXXXXXX Member .......32 XXXXXXXXXX 2 | 
Library .....: XXXXXXXXXX 
Save date and time ....... 3: 11/11/11) 11:11:11 
Restore date and time. .....: 11/11/11 11:11:11 
Expiration date and time ....: 11/11/11 11:11:11 
Number of days used .......: 111111111 
Date last used .........: = 11/11/11 
Use reset date .........: £411/11/11 
EGS eo a era Par Be a Ok Se oe: Ggo we aE XXXXXXXXXXXXXXXXXXXXKXAXAKX KAKA KKK KKAKAA 
XXXXXXXXX 
EJ Bottom 
F3=Exit F12=Cancel [ij 
one | 


Figure 16-8. Example Data Presentation Panel after Scrolling 


The reference numbers in the example panel do not appear on the display. They 
are shown for illustration purposes and also appear in the UIM tag source shown in 
“Source for Example Data Presentation Panel” on page 16-35. These reference 
numbers show which portions of the source define text and information which 
appears on the panel. 


2 


The panel title is defined as text following the period of the display panel 
(PANEL) tag. 


In the first data area, the text for the file, library, and member name is defined 
as text following the period of the data item (DATAI) tag. The file, library, and 
member names are dialog variable values. Each dialog variable is defined 
using the variable definition (VAR) tag. The name of the dialog variable is 
specified on the VAR attribute of the DATAI tag. 


The file name and library are formatted as a qualified object name because 
GRPSEP=QINDENT is specified on the data group (DATAGRP) tag which sur- 
rounds the two DATAI tags. 


The dialog variables for the file name and library name and member name are 
defined using the VAR tags at EJ, EJ, and @@, respectively, shown on page 
16-37. 


This data presentation area is defined by specifying LAYOUT=2 on the DATA 
tag that defines the area. This is shown at [J on page 16-42. 


In the second data area, the text for each item is defined as text following the 
period of the DATAI tag. The value for each item is a dialog variable value. 
Each dialog variable is defined using the VAR tag. The name of the dialog 
variable is specified on the VAR attribute of the DATAI tag. 


Several items in the area show date and time values. This is done by speci- 
fying the dialog variable for the date value on the VAR attribute of the DATAI 
tag and specifying the dialog variable for the time value on the VAR attribute of 
the data item extender (DATAIX) tag. 
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The date and time dialog variables are defined by specifying BASETYPE=DATE 
and BASETYPE=TIME on the class definition (CLASS) tag used to define the 
variables. This is shown at [J on page 16-36. The UIM formats the date 
and time variables according to the date format and separator attributes and 
the time separator attribute of the job. 


The scroll information, More... and Bottom, is shown because the list area is 
defined as scrollable. SCROLL=YES is specified on the DATA tag. 


Each function key is defined using the key list item (KEYI) tag. The text, 
including the function key name, is defined as text following the period of the 
KEYI tag. 


All function keys are defined by placing the KEYI tags between the key list 
(KEYL) and EKEYL tags. The name specified on the NAME attribute of the 
KEYL tag is also specified on the KEYL attribute of the PANEL tag. 


Some function keys, such as Enter, do not have text specified for the KEYI 
tag. In this case, no text appears on the display. However, all function keys 
must be defined using the KEYI tag so the UIM knows what action is assigned 
to each key and what help module to use when help is displayed for the func- 
tion keys. 


Required Tags for a Data Presentation Panel 


Figure 16-9 on page 16-35 shows the required tags for creating a UIM data pres- 
entation panel. For an example of the required and optional tags, see “Source for 
Example Data Presentation Panel” on page 16-35. 


Note: The tags in Figure 16-9 on page 16-35 require attributes. These attributes 
are not shown. Without these attributes, the example in Figure 16-9 on 
page 16-35 will not compile. For a description of the required attributes for 
these required tags, see Appendix A, “UIM Panel Group Definition 
Language.” 
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:PNLGRP. 
:CLASS. 
:ECLASS. = 
7 VAR. 


:DATACOL. 
:DATAT. 
SEDATA. 
:EPANEL. 
:HELP. 


:EHELP. 
:EPNLGRP. 


Figure 16-9. Required UIM Tags for a Data Presentation Panel 


Source for Example Data Presentation Panel 
This is a partial listing of the member T0011PN2 in source file QATTUIM in library 
QUSRTOOL. 


:PNLGRP =HLPSHELF=LIST 
DFTMSGF=t0011msgf2 
SUBMSGF=t0011msgf2. 
eats 
.* The import tag specifies that all help is to be found 
-* in panel group TQO11HL2 searching the library list. 
: IMPORT NAME='*' 
PNLGRP=t0O11h12. 


.* Option 
.* Note: Need WIDTH=1 to preserve column alignment on confirmation panel. 
:CLASS NAME=optcl 
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BASETYPE='ACTION' 
WIDTH=1. 
:ECLASS. 


.* Object name 

:CLASS NAME=namecl 
BASETYPE='OBJNAME 10'. 

:ECLASS. 


.* Library name 
: CLASS NAME=1ibcl 
BASETYPE='OBJNAME 10'. 


:TL. 

:TI VALUE='"*LIBL"'.*LIBL 

:TI VALUE='"*CURLIB"'.*CURLIB 
:ETL. 

:ECLASS. 


.* File attribute 

:CLASS NAME=attrcl 
BASETYPE='CHAR 10' 
CASE=UPPER. 

:ECLASS. 


.* Descriptive text 

: CLASS NAME=textcl 
BASETYPE='IGC 50' 
SUBST=QUOTED. 


-* Source type 

: CLASS NAME=srctypcl 
BASETYPE='CHAR 10'. 

:ECLASS. 


.* Date 

:CLASS -NAME=datecl [j 
BASETYPE='DATE'. 

:TL. 

:TI VALUE='" We 

:TI VALUE='"0000000"'. 

:ETL. 

:ECLASS. 


.* Time 

:CLASS = NAME=timecl [J 
BASETYPE='TIME'. 

:TL. 

:TI VALUE='" My, 

:TI VALUE='"000000"'. 

:ETL. 

:ECLASS. 


-* Yes or No flag class 

: CLASS NAME=yesnocl 
BASETYPE='CHAR 1' 
WIDTH=3. 

=Tk. 

:TI VALUE='"0"' .No 

:TI VALUE='"1"'.Yes 

:ETL. 

:ECLASS. 
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.* Type of file 


: CLASS NAME=typfcl 
BASETYPE='CHAR 1' 
WIDTH=2. 

:TL. 


:TI VALUE='"0Q"'.PF 
:TI VALUE='"1"'.LF 
sETL. 

:ECLASS. 


.* Binary 31 

: CLASS NAME=bin31 
BASETYPE='BIN 31'. 

:ECLASS. 


Additional CLASS tags in member TOQ11PN2 are not shown here 


.* Classes for pad variables in variable 


: CLASS NAME=padicl 
BASETYPE='CHAR 1'. 
:ECLASS. 
: CLASS NAME=pad2cl 
BASETYPE='CHAR 2'. 
:ECLASS. 
: CLASS NAME=pad10cl 
BASETYPE='CHAR 10'. 
:ECLASS. 
: CLASS NAME=pad13cl 
BASETYPE='CHAR 13'. 
:ECLASS. 
: CLASS NAME=pad48cl 
BASETYPE='CHAR 48'. 
:ECLASS. 
: CLASS NAME=pad50cl 
BASETYPE='CHAR 50'. 
:ECLASS. 
es 
eK eer rr 
.* Define all dialog variables 
aK eee eee ne ee eee 
Ex 
aK eee eee nee ee 


i 

.* File name 

:VAR NAME=file [y 
CLASS=namecl. 

i 

.* Library name 

:VAR NAME=lib [J 
CLASS=libcl. 

i 

.* attributes 

:VAR NAME=fattr 
CLASS=attrcl. 

i 

x 

eK per er er 
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-* option for list of members 
: VAR NAME=mopt 
CLASS=optcl. 


i 

.* Object name 

:VAR NAME=mbr 
CLASS=namecl. 

i 

.* member type 

: VAR NAME=mtype 
CLASS=attrcl. 

i 

.* Descriptive text 

: VAR NAME=mtext 
CLASS=textcl. 

x 

eK per re er 

.* Variables for member description 

eK per er ee 

i 

-* Source type 

:VAR NAME=mbrsrc 
CLASS=srctypcl. 

aK eee eee eee eee eee 

.* Creation date 

:VAR NAME=mbrcrtdat 
CLASS=datecl. 

i 

.* Creation time 

:VAR NAME=mbrcrttim 
CLASS=timecl. 

i 

.* Member last source change date 

:VAR NAME=mbrschgdat 
CLASS=datecl. 

i 

.* Member last source change time 

: VAR NAME=mbrschgtim 
CLASS=timecl. 

i 

.* Member remote source file indicator 

:VAR NAME=mbrsrcfi1 
CLASS=yesnocl. 

i 

.* Member remote file indicator 

:VAR NAME=mbrremote 
CLASS=yesnocl. 

SE a at a jp pe “a 

.* Member type of file 

: VAR NAME=mbrtypf 
CLASS=typfcl. 

i 

.* Member ODP sharing 

: VAR NAME=mbrodpshr 
CLASS=yesnocl. 

i 

.* Member current number of records 

:VAR NAME=mbrcurrec 
CLASS=bin31. 

i 

.* Member number of deleted records 

:VAR NAME=mbrd1 trec 
CLASS=bin31. 

aK eee eee e eee eee 
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.* Member 
: VAR 


: VAR 


: VAR 


: VAR 


: VAR 


: VAR 


: VAR 


:VAR 


:VAR 


: VAR 


: VAR 


: VAR 


: VAR 


:VAR 


data space size 
NAME=mbrspcsiz 
CLASS=bin31. 
access path size 
NAME=mbracpsiz 
CLASS=bin31. 


of database file members 


NAME=mbrdbfmbrs 
CLASS=bin31. 
change date. 
NAME=mbrchgdat 
CLASS=datecl. 
change time 
NAME=mbrchgtim 
CLASS=timecl. 
save date 
NAME=mbrsavdat 
CLASS=datecl. 
save time 
NAME=mbrsavtim 
CLASS=timecl. 
restore date 
NAME=mbrrstdat 
CLASS=datecl. 
restore time 
NAME=mbrrsttim 
CLASS=timecl. 
expiration date 
NAME=mbrexpdat 
CLASS=datecl. 
expiration time 
NAME=mbrexptim 
CLASS=timecl. 


number of days used 


NAME=mbrdysuse 
CLASS=bin31. 
date last used 
NAME=mbr1astuse 
CLASS=datecl. 
use reset date 
NAME=mbrrsetdat 
CLASS=datecl. 


.* Variables for padding in variable record definitions. 
.* Padding is needed in variable records so the layout 
.* of the record matches a list format returned from 
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.* an API. The pad variables are used as placeholders for 
.* variables not used in the API format or for reserved space 
-* in the API format. 


eK pee 
: VAR NAME=pad1 
CLASS=padicl. 
:VAR NAME=pad2 
CLASS=pad2cl. 
: VAR NAME=pad10 
CLASS=pad10cl. 
: VAR NAME=pad13 
CLASS=pad13cl. 
: VAR NAME=pad48 
CLASS=pad48cl. 
: VAR NAME=pad50 


CLASS=pad50cl. 


The first VARRCD tags in member TQ011PN2 are not shown here 


+ 


Define a variable record for list of members. 
The layout of this record is designed to match the 
.* List Database File Members API (QUSLMBR) format name MBRLO200. 


+ 


:VARRCD NAME=mbr10200 
VARS='mbr mtype pad13 pad13 mtext' 
NOPUT='pad13' 
NOGET='mtype pad13 mtext' 


* 


Define a variable record for member description. 
The layout of this record is designed to match the 
.* Retrieve Member Description API (QUSRMBRD) format name MBRDOQ200. 


+ 


:VARRCD NAME=mbrd0200 
VARS='pad48 mbrsrc mbrcrtdat mbrcrttim mbrschgdat' 
VARS='mbrschgtim pad50 mbrsrcfil mbrremote mbrtypf' 
VARS='mbrodpshr pad2 mbrcurrec mbrdltrec mbrspcsiz' 
VARS='mbracpsiz mbrdbfmbrs mbrchgdat mbrchgtim mbrsavdat' 
VARS='mbrsavtim mbrrstdat mbrrsttim mbrexpdat mbrexptim' 
VARS='mbrdysuse mbrlastuse mbrrsetdat' 
NOPUT='pad48 pad50 pad2' 
NOGET='pad48 pad50 pad2' 


Additional VARRCD tags in member TQQ11PN2 are not shown here 


All LISTDEF tags in member TOQO11PN2 are not shown here 


-* Condition for physical files 
: COND NAME=pf 
EXPR='fattr="PF mes 


Additional COND tags in member T0011PN2 are not shown here 
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-* Condition for source files 
: COND NAME=srcpf 
EXPR='mbrsrcfil="1"'. 


.* Condition for member in a physical file 


: COND NAME=mbrpf 
EXPR='mbrtypf="0"'. 


.* Condition for member in a logical file 


: COND NAME=mbr1 f 
EXPR='mbrtypf="1""'. 


Additional COND tags in member T0011PN2 are not shown here 
All TT tags in member T0Q11PN2 are not shown here 
All MBAR tags in member TOQ11PN2 are not shown here 


The first KEYL tags in member T0Q11PN2 are not shown here 


.* Define basic key for panels without a command line 


-* or multiple views. 


:KEYL NAME=basickeys [J 
HELP=keyl. 

:KEYI KEY=F1 
HELP=helpf1 
ACTION=HELP. 

:KEYI KEY=F3 
HELP=exit 
ACTION='EXIT SET' 
VARUPD=NO. 

F3=Exit 

:KEYI KEY=F12 
HELP=cancel 
ACTION='CANCEL SET' 
VARUPD=NO. 

F12=Cancel 

sKEYI KEY=F24 
HELP=morekeys 
ACTION=MOREKEYS. 

F24=More keys 

:KEYI KEY=ENTER 
HELP=enter 
ACTION=ENTER. 

:KEYI KEY=HELP 
HELP=help 
ACTION=HELP. 

:KEYI KEY=PAGEDOWN 
HELP=pagedown 
ACTION=PAGEDOWN. 

:KEYI KEY=PAGEUP 
HELP=pageup 
ACTION=PAGEUP. 

:KEYI KEY=PRINT 
HELP=print 
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ACTION=PRINT. 
sEKEYL. 


The first PANEL tags in member TQ011PN2 are not shown here 


* 


> PANEL NAME=dspmbr 
HELP='dspmbr/' 
KEYL=basickeys [jj 
ENTER='RETURN 500' 
TOPSEP=SPACE. 

Display Member Description 1 


* 


.* Define a data presentation area to display the 
.* library/file and member name whose description is displayed. 


eK per en 
:DATA DEPTH=3 

SCROLL=NO 

LAYOUT=2 [J 

BOTSEP=SPACE 

COMPACT 
eK peter ee 


.* Divide the layout width into two columns. 

.* The first column is for the prompt text with leader dots. 
.* The second column is for the variable values. 

:DATACOL WIDTH=22. 

:DATACOL WIDTH='*'. 


.* Display qualified file name 
:DATAGRP GRPSEP=QINDENT 
HELP='dspmbr/filelib' 


COMPACT 
:DATAI VAR=file 

USAGE=OUT 
File 
:DATAI VAR=lib 

USAGE=OUT 
Library 
:EDATAGRP. 
EE 


.* Display member name 

:DATAI  VAR=mbr 
HELP='dspmbr/mbr' 
USAGE=0UT 


Member 


Ke 22-2 --- ee 


.* Define a data presentation area to display the 
.* member definition. 


:DATA DEPTH='*' 


SCROLL=YES [J 
LAYOUT=1 
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BOTSEP=SPACE 


aK eee eee nee 
-* Divide the layout width into two columns. 

.* The first column is for the prompt text with leader dots. 
.* The second column is for the variable values. 

:DATACOL WIDTH=35. 

:DATACOL WIDTH='*'. 


.* Display information about the file 
:DATAGRP GRPSEP=NONE 
COMPACT 


.* Display type of file 

:DATAI VAR=mbrtypf 
HELP='dspmbr/mbrtypf' 
USAGE=OUT 


Type of file 

eK per ee ee 

.* Display remote file 

:DATAI VAR=mbrremote 
HELP='dspmbr/mbrremote' 
USAGE=OUT 


Remote file 

eK eer ee ee 

.* Display ODP sharing 

:DATAI VAR=mbrodpshr 
HELP='dspmbr/mbrodpshr' 
USAGE=0UT 


Allow ODP sharing 
: EDATAGRP. 
eK eee re 
.* Display information only if file is a source file 
:DATAGRP GRPSEP=NONE 
COMPACT 
COND=srcpf 


aK eee eee nee ee 
.* Display source type 
:DATAI VAR=mbrsrc 
HELP='dspmbr/mbrsrc' 
USAGE=OUT 


Source type 
eK per eee 
.* Display last source change date and time 
:DATAI VAR=mbrschgdat 
HELP='dspmbr/mbrschgdt ' 
USAGE=OUT 


Last source change date and time 
:DATAIX VAR=mbrschgtim 
USAGE=0UT 


: EDATAGRP. 


wR eee eee nee ee eee 
.* Display create and change information 
:DATAGRP GRPSEP=NONE 

COMPACT 
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aK eee eee eee 

.* Display creation date and time 

:DATAI VAR=mbrcrtdat 
HELP='dspmbr/mbrcrtdt' 
USAGE=OUT 


Creation date and time 
:DATAIX  VAR=mbrerttim 
USAGE=OUT 


KO eee eee nee ee 

.* Display change date and time 

:DATAI VAR=mbrchgdat 
HELP='dspmbr/mbrchgdt ' 
USAGE=0UT 


Change date and time 
:DATAIX VAR=mbrchgtim 
USAGE=0UT 


: EDATAGRP. 


.* Display information about the size of the member 
:DATAGRP GRPSEP=NONE 
COMPACT 


.* Display current records for physical file member 
:DATAI VAR=mbrcurrec 

COND=mbrpf 

HELP='dspmbr/mbrcurrec' 

USAGE=OUT 


Number of records 
eK eer ee ee 
.* Display current index entries for logical file member 
:DATAI VAR=mbrcurrec 
COND=mbr1 f 
HELP='dspmbr/mbrcurrec' 
USAGE=OUT 


Number of index entries 

eK per ee ee 

.* Display deleted records 

:DATAI VAR=mbrd1trec 
HELP='dspmbr/mbrditrec' 
USAGE=OUT 


Deleted records 
eK peter ee 
.* Display data space size for physical file member 
:DATAI VAR=mbrspcsiz 
COND=mbrpf 
HELP='dspmbr/mbrspcsiz' 
USAGE=OUT 


Data space size 

aK eee eee nee 

.* Display access path size 

:DATAI VAR=mbracpsiz 
HELP='dspmbr/mbracpsiz' 
USAGE=OUT 
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Access path size 
eK pee re 
.* Display database file members for logical file member 
:DATAI VAR=mbrdbfmbrs 
COND=mbr1 f 
HELP='dspmbr/mbrdbfmbrs ' 
USAGE=OUT 


Number of database file members 
: EDATAGRP. 


.* Display save restore information 
:DATAGRP GRPSEP=NONE 
COMPACT 


.* Display save date and time 

:DATAI —- VAR=mbrsavdat 
HELP='dspmbr/mbrsavdt' 
USAGE=OUT 


Save date and time 
:DATAIX VAR=mbrsavtim 
USAGE=OUT 


aK eee eee eee ee 

.* Display restore date and time 

:DATAI VAR=mbrrstdat 
HELP='dspmbr/mbrrstdt' 
USAGE=OUT 


Restore date and time 
:DATAIX  VAR=mbrrsttim 
USAGE=OUT 


: EDATAGRP. 

eK per ee ee 

.* Display expiration date 

:DATAI VAR=mbrexpdat 
HELP='dspmbr/mbrexpdt ' 
USAGE=0UT 


Expiration date and time 
:DATAIX VAR=mbrexptim 
USAGE=0UT 


aK eee eee nee ee ee 
.* Display usage information 
:DATAGRP GRPSEP=NONE 

COMPACT 


eK eee eee nee ee ee 

.* Display number of days used 

:DATAI VAR=mbrdysuse 
HELP='dspmbr/mbrdysuse' 
USAGE=OUT 


Number of days used 

eK eee eee eee ee ee 

.* Display date last used 

:DATAI VAR=mbrlastuse 
HELP='dspmbr/mbrlastuse' 
USAGE=OUT 


Chapter 16. Introduction to the User Interface Manager 


16-45 


Date last used 


.* Display use reset date 

:DATAI VAR=mbrrsetdat 
HELP='dspmbr/mbrrsetdat ' 
USAGE=OUT 


Use reset date 
: EDATAGRP. 


.* Display text description 

:DATAI VAR=mtext 
HELP='dspmbr/text ' 
USAGE=OUT 


Text 


* 


:EDATA. 


* 


:EPANEL. 
Additional PANEL tags in member T0Q11PN2 are not shown here 
x 


.* End of panel group source 
KR ww ww ww we ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee ee 


:EPNLGRP. 


Application Programming for a Data Presentation Panel 
An example of an application program to display the data presentation panel shown 
in Figure 16-7 on page 16-32 can be found in member T0011CP3 in file 
QATTSYSC in library QUSRTOOL. This is an ILE C program which calls the 
appropriate UIM application programming interfaces (APIs) to display the panel. 
This program is called by the UIM to process option 5 (Display) from the example 
list panel shown in Figure 16-3 on page 16-14. 


A general example of an RPG application written using the UIM APIs can be found 
in QUSRTOOL. Refer to member T0011INF in source file QATTINFO in library 
QUSRTOOL. 


To write a program in any language to display the example data presentation panel, 
the program should do the following: 


1. If the program is not called by the UIM to process option 5 from the example 
list panel shown in Figure 16-3 on page 16-14, the program should first do the 
following. For example, this would be the case if the user could display the 
member description directly by using a CL command. 


a. Call the Open Display Application (QUIOPNDA) API to open the panel 
group. The panel group must already be created using the Create Panel 
Group (CRTPNLGRP) command. 


b. Set up a buffer containing the values for the following dialog variables: 
FILE A CHAR 10 variable which is the name of the file. 


LIB A CHAR 10 variable which is the name of the library where the 
file resides. 
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FATTR A CHAR 10 variable which is the file attribute of the file. This 
variable is used to condition on list options which are only allowed 
for physical files. 


c. Call the Put Dialog Variable (QUIPUTV) API to change the contents of the 
dialog variables using variable record FILELIB and the buffer initialized in 
the previous step. 


d. Set up a buffer containing values for the following dialog variables: 
MBR A CHAR 10 variable which is the member name. 
MTYPE A CHAR 10 variable which is the member type. 

PAD13 A CHAR 13 reserved space in the buffer. 
PAD13 A CHAR 13 reserved space in the buffer. 


MTEXT A CHAR 50 variable which is the descriptive text for the 
member. 


Note: The layout of this buffer is designed to match with the layout of the 
entries in the user space returned by the QUSLMBR API. There- 
fore, instead of setting up a buffer, the application program can 
pass the buffer as it exists in the user space. 


e. Call the Put Dialog Variable (QUIPUTV) API to change the contents of the 
dialog variables using variable record MBRLO200 and the buffer initialized 
in the previous step. 


Note: If the program is called by the UIM to process option 5 from the 
example list panel, the file name and library name were already set by 
the application program before displaying the list panel. Also, when the 
UIM performs list option processing, the MBR, MTYPE, and MTEXT 
dialog variables will already be set to the values from the list entry 
which calls the application program to process option 5. 


. Set up a buffer containing values for the following dialog variables: 


PAD48 A CHAR 48 reserved space in the buffer. 
MBRSRC A CHAR 10 variable which is the source type for the 
member. 


MBRCRTDAT A CHAR 7 variable which is the creation date for the 
member in the form required for BASETYPE=DATE dialog 
variables. 


MBRCRTTIM A CHAR 6 variable which is the creation time for the 
member in the form required for BASETYPE=TIME dialog var- 
iables. 


MBRSCHGDAT A CHAR 7 variable which is the source changed date for 
the member in the form required for BASETYPE=DATE dialog 
variables. 


MBRSCHGTIM A CHAR 6 variable which is the source changed time for 
the member in the form required for BASETYPE=TIME dialog 


variables. 
PAD50 A CHAR 50 reserved space in the buffer. 
MBRSRCFIL A CHAR 1 variable indicating whether or not the member is 


in a source file ("O"=no, "1"=yes). 
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MBRREMOTE 


MBRTYPF 


MBRODPSHR 


PAD2 
MBRCURREC 


MBRDLTREC 


MBRSPCSIZ 


MBRACPSIZ 


MBRDBFMBRS 


MBRCHGDAT 


MBRCHGTIM 


MBRSAVDAT 


MBRSAVTIM 


MBRRSTDAT 


MBRRSTTIM 


MBREXPDAT 


MBREXPTIM 


MBRDYSUSE 


MBRLASTUSE 
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A CHAR 1 variable indicating whether or not the member is 
in a remote file ("O"=no, "1"=yes). 


A CHAR 1 variable indicating whether the member is in a 
physical or logical file ("O"=physical "1"=logical). 


A CHAR 1 variable indicating whether or not ODP sharing 
is allowed for the member ("0"=no, "1"=yes). 


A CHAR 2 reserved space in the buffer. 


A BINARY 4 variable containing the number of records in 
the member. 


A BINARY 4 variable containing the number of deleted 
records in the member. 


A BINARY 4 variable containing the size of the space for 
the member. 


A BINARY 4 variable containing the access path size for 
the member. 


A BINARY 4 variable containing the number of database 
file members for this logical file member. 


A CHAR 7 variable which is the last changed date for the 
member in the form required for BASETYPE=DATE dialog 
variables. 


A CHAR 6 variable which is the last changed time for the 
member in the form required for BASETYPE=TIME dialog var- 
iables. 


A CHAR 7 variable which is the date the member was last 
saved in the form required for BASETYPE=DATE dialog vari- 
ables. 


A CHAR 6 variable which is the time the member was last 
saved in the form required for BASETYPE=TIME dialog vari- 
ables. 


A CHAR 7 variable which is the date the member was last 
restored in the form required for BASETYPE=DATE dialog 
variables. 


A CHAR 6 variable which is the time the member was last 
restored in the form required for BASETYPE=TIME dialog var- 
iables. 


A CHAR 7 variable which is the date of expiration for the 
member in the form required for BASETYPE=DATE dialog 
variables. 


A CHAR 6 variable which is the time of expiration for the 
member in the form required for BASETYPE=TIME dialog var- 
iables. 


A BINARY 4 variable containing the number of days the 
member has been used. 


A CHAR 7 variable which is the date the member was last 
used in the form required for BASETYPE=DATE dialog vari- 
ables. 


MBRRSETDAT A CHAR 7 variable which is the date the use information 
was reset for the member in the form required for 
BASETYPE=DATE dialog variables. 


Note: The layout of this buffer is designed to match with the layout of the data 
returned by the Retrieve Member Description (QUSRMBRD) API using 
format name MBRDO200. Therefore, instead of setting up a buffer, the 
application program can pass the buffer as it is returned by the API. 


3. Call the Put Dialog Variable (QUIPUTV) API to change the contents of the 
dialog variables using variable record MBRDO200 and the buffer initialized in 
the previous step. 


4. Call the Display Panel (QUIDSPP) API to display panel WRKMBR. The UIM 
returns control to the application when one of the following occurs: 


e The user presses the Enter key without typing any list options or a 
command on the command line. The program variable passed as the func- 
tion requested parameter to the QUIDSPP API is set to 500. This is done 
because ENTER='RETURN 500' is specified on the PANEL tag which defines 
the WRKMBR panel. 


e The user presses the F12 (Cancel) key. The program variable passed as 
the function requested parameter to the QUIDSPP API is set to -8. This is 
the value defined for the CANCEL dialog command. 


e The user presses the F3 (Exit) key. The program variable passed as the 
function requested parameter to the QUIDSPP API is set to -4. This is the 
value defined for the CANCEL dialog command. 


5. If the program is not called by the UIM to process option 5 from the example 
list panel shown in Figure 16-3 on page 16-14, the program should do the fol- 
lowing. 


a. Call the Close Application (QUICLOA) API to close the UIM application. 
This frees up the system resources being used by the UIM application. 


Data Entry Panel 
A data entry panel is a form of data presentation panel where the user is allowed to 
enter new values for one or more of the dialog variables displayed. The USAGE 
attribute of the data item (DATAI) and data item extender (DATAIX) tags defines 
whether or not the user is allowed to enter a new value for the dialog variable dis- 
played by the tag. 


When USAGE=INOUT is specified, the user is allowed to enter a new value for the 
dialog variable. For data areas using a vertical layout, the leader dots following the 
descriptive text for the item end with a period instead of a colon. A colon is used 
for data items which do not allow input. 


When the UIM returns control from the Display Panel (QUIDSPP) API and the func- 
tion requested parameter contains the value specified for the RETURN dialog 
command on the ENTER attribute of the display panel (PANEL) tag, the application 
program uses the Get Dialog Variable (QUIGETV) API to retrieve the values for the 
dialog variables changed by the user. 
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Creating a Panel with a Menu Bar 


A menu bar can be defined for any full-screen panel. The menu bar acts as an 
extension of the panel and contains definitions of choices for the menu bar. Each 
choice in the menu bar has a pull-down menu defined. When the user selects the 
menu bar choice, the UIM displays the pull-down menu in a window below the 
menu bar. Each choice within the pull-down menu represents an action which can 
be performed. In this example, a Work with File Members panel is defined using a 
menu bar. This panel is functionally similar to the panel shown in “Creating a List 
Panel” on page 16-13. Although the panel appears slightly different from the 
example list panel, this example panel using a menu bar performs the same func- 
tion. 


The panel shown in Figure 16-10 shows an example of an action list panel which 
also has a menu bar. This example explains how the menu bar is defined and how 
it interacts with the rest of the panel definition. This example does not describe 
how to define the action list portion of the panel. For more information on creating 
an action list, see “Creating a List Panel” on page 16-13. If you need more infor- 
mation on creating help for a menu bar area, see “Help in a Menu Bar Area” on 
page 19-13. 


The example panel is shown with a pull-down menu displayed. The pull-down is 
active because the user selected entries in the list and pressed the Enter key. 


Member View Help 


_ 3. Copy... : File Members 
4. Remove 4 
5. Display... : F4 for list 
library, *CURLIB, *LIBL 
7. Reorganize 
8. Member description... 
9. Clear... 
90. Exit F3  : XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKAAXXXX 


FD. ©, 0.0.0. 0,0, 0.0,0.0,0.0.0.0.0,0,0.0.0.0,0.0.0.0,0,0.0.0.0.0.0.0.0.0,0,0,04 
XXXXXXXXXX  XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXKXXXXKXKXKKXKX KKK XK XK XK XK AK 
XXXXXXXXXX  XXXXXXXXXX AXXXXXXXXXXXXXXXXXXXKXXXXKXKXKKXAKX KKK XK XK XK XK XK 
XXXXXXXXXX  XXXXXXXXXX XAXXXXXXXXXXXXXXXXXXXKXKXXKXKXKKXKX KKK XK XK XK XK AK 
XXXXXXXXXX  XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXKXXXXKXKXKKXKX KKK XK XK XK KK XK 
XXXXXXXXXX  XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXKXXXXKXKXKKXKX KAKA XKX XK XK XK XK 
XXXXXXXXXX  XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXKXXXXKXKXKKXKX KKK XK XK XK KK XK 
XXXXXXXXXX  XXXXXXXXXX XXXXXXXXXXXXXXXXXXXXKXXXXKXKXKKXKX KKK XK XK XK KK AK 

More... 


™I 


Parameters for options 3 and 5 or command 
===> 


F3=Exit F4=Prompt F9=Retrieve F1Q=Actions  F12=Cancel 


Figure 16-10. Example Panel with a Menu Bar 


The reference numbers in the example panel do not appear on the display. They 
are shown for illustration purposes and also appear in the UIM tag source shown in 
“Source for Example Panel with a Menu Bar” on page 16-53. These reference 
numbers show which portions of the source define text and information which 
appears on the panel. 


Each choice in the menu bar is defined using a menu bar choice (MBARC) 
tag. The choice shown on the panel is defined as text following the period of 
the MBARC tag. 
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All choices for a menu bar are defined by placing the MBARC tags between 
the menu bar (MBAR) and EMBAR tags. The name specified on the NAME 
attribute of the MBAR tag is also specified on the MBAR attribute of the PANEL 
tag. 


fs Each option in the pull-down menu is defined using the pull-down field choice 
(PDFLDC) tag. The option number is defined using the OPTION attribute and 
the text following the option number is defined as text following the period of 
the PDFLDC tag. 


All choices for a pull-down menu are defined by placing the PDFLDC tags 
between the pull-down field (PDFLD) and EPDFLD tags. The PDFLDC and 
EPDFLDC tags are placed between a MBARC and EMBARC tag. 


An accelerator key description shown along the right side of the pull-down 
menu is defined as text following the period of the PDACCEL tag. An accel- 
erator is a key which performs the same function as an option in a pull-down 
menu. The PDACCEL tag is placed immediately after the PDFLDC tag for 
the option to which the accelerator applies. 


From this panel, the application user can perform operations against entries in the 
list using either of the following methods: 


e When the user selects entries in the list and presses the Enter key, the UIM 
displays the pull-down menu for the member choice in the menu bar. This is 
done because SELECT=PULLDOWN is specified on the PANEL tag shown at 
EY on page 16-60. 


When the user selects option 3, 4, 5, 7, 8 or 9 from the pull-down menu, the 
UIM performs the action defined for that option once for each list entry selected 
by the user. The UIM does this because ACTFOR=LIST is specified on the 
PDFLDC tag at [J on page 16-57. The UIM makes these options unavailable 
when the users displays the pull-down menu without selecting any entries in 
the list. 


When the user selects option 90 from the pull-down menu, the UIM returns 
control to the application program that displayed the panel. The UIM does this 
because ACTFOR=PANEL is specified on the PDFLDC tag at on page 16-58. 
Because EXIT is specified for the ACTION attribute on the PDFLDC tag, the UIM 
returns control to the calling program with an indication that the user requested 
Exit. 


e When the user types option numbers next to the desired list entries and 
presses the Enter key, the UIM performs the action for each option. The UIM 
does this because ACTOR=UIM is specified on the list area (LIST) tag at [J on 
page 16-61 and a list action (LISTACT) tag at [EJ on page 16-62 specifies the 
action for the UIM to perform for each option number. 


Note that in this case, no text is shown on the panel describing the option 
numbers for the list. This is because no text is specified following the period of 
the LISTACT tags. The primary interface defined for this panel is to select 
entries in the list and then choose an action from a pull-down menu. The list 
option numbers are available as a faster alternative for more experienced 
users. Although the list option numbers do not appear on the panel, they are 
described in the help shown when the Help key is pressed with the cursor posi- 
tioned in the input column of the list. 


For this example, the actions for the option numbers in the pull-down menu are 
the same as the actions for the option numbers that can be entered in the list. 
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This design is recommended for a consistent user interface, but the UIM does 
not prevent the application developer from defining an action in a pull-down 
menu that is different from the action for a list option with the same option 
number. 


Required Tags for a Panel with a Menu Bar 
Figure 16-11 shows the required tags for creating a UIM panel with a menu bar. 
For an example of the required and optional tags, see “Source for Example Panel 
with a Menu Bar” on page 16-53. 


Note: The tags in Figure 16-11 require attributes. These attributes are not 
shown. Without these attributes, the example in Figure 16-11 will not 
compile. For a description of the required attributes for these required tags, 
see Appendix A, “UIM Panel Group Definition Language.” 


:PNLGRP. 


:CLASS. 
"ECLASS. — 
VAR. 


:MBAR. 
:MBARC. 
:PDFLD. 
:PDFLDC. 


:EPDFLD. 
: EMBARC. 


:EPANEL. 
:HELP. 


:EHELP. 
: EPNLGRP. 


Figure 16-11. Required UIM Tags for a Panel with a Menu Bar 
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Source for Example Panel with a Menu Bar 
This is a partial listing of member T0011PN2 in source file QATTUIM in library 
QUSRTOOL. 


:PNLGRP =HLPSHELF=LIST 
DFTMSGF=t0011msgf2 
SUBMSGF=t0011msgf2. 
x 
.* The import tag specifies that all help is to be found 
-* in panel group TOQ11HL2 found by searching the library list. 
:IMPORT NAME='x' 
PNLGRP=tO011h12. 


.* Option 
.* Note: Need WIDTH=1 to preserve column alignment on confirmation panel. 
: CLASS NAME=optcl 
BASETYPE='ACTION' 
WIDTH=1. 
:ECLASS. 


.* Object name 

:CLASS NAME=namecl 
BASETYPE='OBJNAME 10'. 

:ECLASS. 


.* Library name 
: CLASS NAME=1ibcl 
BASETYPE='OBJNAME 10'. 


TI VALUE='"*LIBL"' .*LIBL 
TI VALUE='"*CURLIB"' .*CURLIB 


.* File attribute 

:CLASS NAME=attrcl 
BASETYPE='CHAR 10' 
CASE=UPPER. 

:ECLASS. 


.* Descriptive text 

: CLASS NAME=textcl 
BASETYPE='IGC 50' 
SUBST=QUOTED. 

:ECLASS. 


.* Source type 
: CLASS NAME=srctypcl 
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BASETYPE='CHAR 10’. 
:ECLASS. 


Additional CLASS tags in member TOO11PN2 are not shown here 


.* Command line parameters 
: CLASS NAME=parmcl 
BASETYPE='CHAR 255'. 


.* Exit program specification for CALL dialog command 
: CLASS NAME=exitcl 

BASETYPE='CHAR 20'. 
:ECLASS. 


.* View number 

:CLASS NAME=vwnumc | 
BASETYPE='BIN 15'. 

:ECLASS. 


.* Classes for pad variables in variable record definitions. 

: CLASS NAME=pad1cl 
BASETYPE='CHAR 1'. 

:ECLASS. 

: CLASS NAME=pad2cl 
BASETYPE='CHAR 2'. 

:ECLASS. 

: CLASS NAME=pad10cl 
BASETYPE='CHAR 10'. 

:ECLASS. 

: CLASS NAME=pad13cl 
BASETYPE='CHAR 13'. 

:ECLASS. 

: CLASS NAME=pad48cl 
BASETYPE='CHAR 48'. 

:ECLASS. 

: CLASS NAME=pad50cl 
BASETYPE='CHAR 50'. 


:ECLASS. 
x 
eK ee a ee eee 
.* Define all dialog variables 
eR ee a er ee eee 
x 
eK pee eee ee ee ee ee 
.* Variables for file and library 
eK pee eee ee ee ee 
7 
.* File name 
: VAR NAME=file 
CLASS=namecl . 
ee 
.* Library name 
: VAR NAME=1ib 
CLASS=libcl. 
7 
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.* attributes 
:VAR NAME=fattr 
CLASS=attrel. 


7 
x 
eK eee eee ee ee ee ee 
.* Variables for list of members 
eK eee eee ee ee ee 
7 
-* option for list of members 
: VAR NAME=mopt 
CLASS=optcl. 
7 
.* Object name 
: VAR NAME=mbr 
CLASS=namecl . 
7 
.* member type 
: VAR NAME=mtype 
CLASS=attrcl. 
ee 
.* Descriptive text 
: VAR NAME=mtext 


CLASS=textcl. 


Additional VAR tags in member TQO11PN2 are not shown here 


x 
eK eee eee ee ee ee ee 
.* Variable for command line parameters 
eK eee eee ee ee ee ee 
ee 
.* Command line parameters 
: VAR NAME=parms 

CLASS=parmcl . 
x 
eK eee eee ee ee ee ee ee 
.* Variables for specifying CALL/exit programs 
eK eee eee ee ee ee 
7 
.* Program to call for all UIM exits 
: VAR NAME=exitpgm 

CLASS=exitcl. 
x 
eK eee eee ee ee ee ee ee 
.* Variables for controlling list views 
eK eee eee ee ee ee ee 
7 
.* View number for list of members 
: VAR NAME=mbrvi ew 


CLASS=vwnumcl . 
Additional VAR tags in member TQO11PN2 are not shown here 


x 
Ko eee eee e nnn eee ee ee 
.* Variables for padding in variable record definitions. 
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Padding is needed in variable records so the layout 

of the record matches a list format returned from 

an API. The pad variables are used as placeholders for 
variables not used in the API format or for reserved space 
in the API format. 


* + FF F 


eK eee eee ee ee ee ee 
: VAR NAME=pad1 
CLASS=padicl. 
: VAR NAME=pad2 
CLASS=pad2cl. 
: VAR NAME=pad10 
CLASS=pad10cl. 
: VAR NAME=pad13 
CLASS=pad13cl. 
: VAR NAME=pad48 
CLASS=pad48cl. 
: VAR NAME=pad50 
CLASS=pad50cl1. 
x 
eR ee ee eee 
.* Define a variable record for file, library and file attribute 
eK ee ee eee 


:VARRCD NAME=filelib 
VARS='file lib fattr' 
NOGET='fattr' 


:VARRCD NAME=exitprog 
VARS='exitpgm' 


.* Define a variable record for list of members. 
.* The layout of this record is designed to match the 
.* List Database File Members API (QUSLMBR) format name MBRLO200. 


:VARRCD NAME=mbr10200 
VARS='mbr mtype pad13 pad13 mtext' 


NOPUT='pad13' 
NOGET='mtype pad13 mtext' 


Additional VARRCD tags in member TOQO11PN2 are not shown here 


:LISTDEF NAME=mbrlist 
VARS='mopt mbr mtype mtext' 
MSGID=USRO101. 


Additional LISTDEF tags in member TOO11PN2 are not shown here 
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Xx 


K ewww eee eee eee eee eee eee eee eee ee eee eee wee wee eee eee ee ee eee eee eee eee 


.* Define all conditions 


.* Condition for physical files 
: COND NAME=pf 
EXPR=' fattr="PF ney 


.* Conditions for views of members list 

: COND NAME=mbrview1 
EXPR='mbrview=0'. 

: COND NAME=mbrview2 
EXPR='mbrview=1'. 


Additional COND tags in member TOO11PN2 are not shown here 


All TT tags in member TOQ11PN2 are not shown here 


:MBAR NAME=mbarmbr 
HELP='mbarmbr/ ' 


:MBARC HELP='mbarmbr/member' 


Member 
:PDFLD. 
:PDFLDC OPTION=3 
ACTFOR=LIST [J 
HELP='mbarmbr/cpyf ' 
ACTION='CMD CPYF ?*FROMFILE(&lib./&file.)' 
ACTION=' ?*FROMMBR(&mbr.) &parms. ' 


Copy... 


x 
:PDFLDC OPTION=4 

ACTFOR=LIST 

HELP='mbarmbr/rmvm' 

ACTION='CMD RMVM FILE(&lib./&file.) MBR(&mbr.)' 
.* CONFIRM=confrmvmmb 

USREXIT='CALL exitpgm' 


Remove... 
* 
:PDFLDC OPTION=5 
COND=pf 
ACTFOR=LIST 
HELP='mbarmbr/dsppfm' 
ACTION='CMD DSPPFM FILE(&lib./&file.) MBR(&mbr.) &parms. ' 


Display... 
* 


:PDFLDC OPTION=7 
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COND=pf 

ACTFOR=LIST 

HELP='mbarmbr/rgzm' 

ACTION='CMD RGZPFM FILE(&lib./&file.) MBR(&mbr.) ' 


Reorganize 

x 

:PDFLDC OPTION=8 
ACTFOR=LIST 
HELP='mbarmbr/dspfd' 
ACTION='CALL exitpgm' 


Member description... 
x 
:PDFLDC OPTION=9 
COND=pf 
ACTFOR=LIST 
HELP='mbarmbr/clrm' 
.* CONFIRM=confclrmmb 
ACTION='CMD CLRPFM FILE(&lib./&file.) MBR(&mbr.) ' 


Clear... 

x 

:PDFLDC OPTION=90 
ACTFOR=PANEL 
HELP='mbarmbr/exit' 
ACTION='EXIT SET' 


VARUPD=NO 
Exit 
:PDACCEL.F3 
:EPDFLD. 
: EMBARC. 


x 


:MBARC HELP='mbarmbr/view' 


View 

:PDFLD. 

:PDFLDC OPTION=1 
ACTFOR=PANEL 
HELP='mbarmbr/view2' 
AVAIL=mbrview1 
ACTION=CHGVIEW 


Names only 

:PDACCEL.F11 

:PDFLDC OPTION=2 
ACTFOR=PANEL 
HELP='mbarmbr/view1' 
AVAIL=mbrview2 
ACTION=CHGVIEW 


Names and descriptions 
:PDACCEL.F11 

: EPDFLD. 

: EMBARC. 

x 


:MBARC HELP='mbarmbr/help' 
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Help 

:PDFLD. 

:PDFLDC OPTION=1 
ACTFOR=PANEL 
HELP='mbarmbr/helphelp' 
ACTION=helphelp 


Help for help... 

:PDFLDC OPTION=2 
ACTFOR=PANEL 
HELP='mbarmbr/exthelp' 
ACTION=exthelp 


Extended help... 

:PDFLDC OPTION=3 
ACTFOR=PANEL 
HELP='mbarmbr/keyshelp' 
ACTION=keyshelp 


Keys help... 

:PDFLDC OPTION=4 
ACTFOR=PANEL 
HELP='mbarmbr/about ' 
ACTION='DSPHELP about' 


About... 
:EPDFLD. 
: EMBARC. 
: EMBAR. 


The first KEYL tags in member TOO11PN2 are not shown here 


.* Define keys for work with members panel with a menu bar 
.* The keys are the same but some do not have descriptions 


:KEYL NAME=mbrkeysmb 
HELP=keyl. 

:KEYI KEY=F1 
HELP=helpf1 
ACTION=HELP. 

:KEYI KEY=F3 
HELP=exit 
ACTION='EXIT SET' 
VARUPD=NO. 

F3=Exit 

:KEYI KEY=F4 
HELP=prompt 
ACTION=PROMPT 
PRIORITY=30. 

F4=Prompt 

:KEYI KEY=F9 
HELP=retrieve 
ACTION=RETRIEVE 
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PRIORITY=35. 
F9=Retrieve 
:KEYI KEY=F10 
HELP=actions 
ACTION=ACTIONS 
PRIORITY=40. 
F10=Actions 
:KEYI KEY=F11 
HELP=mbrviewname 
ACTION=CHGVIEW 
COND=mbrview1. 
:KEYI KEY=F11 
HELP=mbrviewdesc 
ACTION=CHGVIEW 
COND=mbrview2. 
:KEYI KEY=F12 
HELP=cancel 
ACTION='CANCEL SET' 
VARUPD=NO. 
F12=Cancel 
:KEYI KEY=F24 
HELP=morekeys 
ACTION=MOREKEYS. 
F24=More keys 
:KEYI KEY=ENTER 
HELP=enter 
ACTION=ENTER. 
:KEYI KEY=HELP 
HELP=help 
ACTION=HELP. 
:KEYI KEY=PAGEDOWN 
HELP=pagedown 
ACTION=PAGEDOWN. 
:KEYI KEY=PAGEUP 
HELP=pageup 
ACTION=PAGEUP. 
:KEYI KEY=PRINT 
HELP=print 
ACTION=PRINT. 
:EKEYL. 


Additional KEYL tags in member TOOQ11PN2 are not shown here 


The first PANEL tags in member TOQ11PN2 are not shown here 


: PANEL NAME=wrkmbrmbar 
HELP='wrkmbr/' 
MBAR=mbarmbr 
KEYL=mbrkeysmb 
ENTER='RETURN 500' 
SELECT=PULLDOWN 
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TOPSEP=SPACE. 
Work with File Members 


.* Define a data presentation area to display the 
.* library/file name whose members are listed. 


eK pee eee ee ee ee ee ee ee 
:DATA DEPTH=3 

SCROLL=NO 

LAYOUT=1 

BOTSEP=SPACE 

COMPACT 
eK eee eee ee ee ee ee ee 


.* Divide the layout width into two columns. 

.* The first column is for the prompt text with leader dots. 
.* The second column is for the variable values. 

:DATACOL WIDTH=22. 

:DATACOL WIDTH=12. 

:DATACOL WIDTH='*'. 


.* Display qualified file name 

:DATAGRP GRPSEP=QINDENT 
HELP='wrkmbr/filelib' 
COMPACT 


:DATAI VAR=file 
USAGE=INOUT 
CSRLOC=NO 
PROMPT='CALL exitpgm' 


File 

:DATAC.F4 for list 

:DATAI VAR=1ib 
USAGE=INOUT 
CSRLOC=NO 


Library 
:DATAC.1ibrary, *CURLIB, *LIBL 
: EDATAGRP. 


:LIST DEPTH='«' 
LISTDEF=mbrlist 
ACTOR=UIM_ [f} 
MAXHEAD=4 
MAXACTL=3 
VIEW=mbrview 
PARMS=parms 
BOTSEP=SPACE. 
:TOPINST.Select members using /, press Enter. 


.* Specify the action to be taken for each option 
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:LISTACT OPTION=3 [ 
NOCMD=PROMPT 
HELP='wrkmbr/cpyf ' 
ENTER='CMD CPYF ?*FROMFILE(&lib./&file.)' 
ENTER=' ?*FROMMBR(&mbr.) &parms. ' 
PROMPT='CMD ?CPYF ?*FROMFILE(&lib./&file.)' 
PROMPT=' ?*FROMMBR(&mbr.) &parms.'. 
x 
:LISTACT OPTION=4 
HELP='wrkmbr/rmvm' 
.* CONFIRM=confrmvmmb 
ENTER='CMD RMVM FILE(&lib./&file.) MBR(&mbr.) ' 
PROMPT='CMD ?RMVM ?*FILE(&lib./&file.) ?*MBR(&mbr.) ' 
USREXIT='CALL exitpgm'. 
x 
:LISTACT OPTION=5 
COND=pf 
HELP='wrkmbr/dsppfm' 
ENTER='CMD DSPPFM FILE(&lib./&file.) MBR(&mbr.) &parms.' 
PROMPT='CMD DSPPFM ?*FILE(&lib./&file.) ?*MBR(&mbr.) &parms.'. 
x 
:LISTACT OPTION=7 
COND=pf 
HELP='wrkmbr/rgzm' 
ENTER='CMD RGZPFM FILE(&lib./&file.) MBR(&mbr.) ' 
PROMPT='CMD ?RGZPFM ?*FILE(&lib./&file.) ?*MBR(&mbr.)'. 
x 
:LISTACT OPTION=8 
HELP='wrkmbr/dspfd' 
ENTER='CALL exitpgm' 
PROMPT='CALL exitpgm'. 
x 
:LISTACT OPTION=9 
COND=pf 
HELP='wrkmbr/clrm' 
.* CONFIRM=confcl rmmb 
ENTER='CMD CLRPFM FILE(&lib./&file.) MBR(&mbr.) ' 
PROMPT='CMD ?CLRPFM ?*FILE(&lib./&file.) ?*MBR(&mbr.)'. 


x 


:LISTCOL VAR=mopt 
USAGE=INOUT 
HELP='wrkmbr/option' 
MAXWIDTH=6. 

:LISTCOL VAR=mbr 
USAGE=OUT 
HELP='wrkmbr/mbr' 
MAXWIDTH=10. 

Member 

:LISTCOL VAR=mtype 
USAGE=OUT 
HELP='wrkmbr/type' 
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MAXWIDTH=10. 


Type 

:LISTCOL VAR=mtext 
USAGE=OUT 
HELP='wrkmbr/text' 
MAXWIDTH='*'. 

Text 

x 


Ko eee eee e nn ene ee ee ee 
.* Define multiple views for Fll to toggle between 


:LISTVIEW COLS='mopt mbr mtype mtext'. 
:LISTVIEW COLS='mopt mbr' layout=4. 


:CMDLINE SIZE=SHORT. 
Parameters for options 3 and 5 or command 
* 


: EPANEL. 
Additional PANEL tags in member TOO11PN2 are not shown here 


x 
KK eee eee ee ee eee eee eee ee eee eee eee eee eee eee ewe eee eee eee eee eee eee eee 


.* End of panel group source 
K esse eee eee ee ee ee eee eee eee ee eee eee wee ee ee eee ee eee eee ee eee eee eee 


:EPNLGRP. 


Application Programming for a Menu Bar Panel 


An example of an application program to display the panel shown in Figure 16-10 
on page 16-50 can be found in member T0011CP2 in source file QATTSYSC in 
library QUSRTOOL. This is an ILE C program which calls the appropriate UIM 
application programming interfaces (APIs) to display the panel. 


The application program should do the processing described in “Application Pro- 
gramming for a List Panel” on page 16-25. 


A general example of an RPG program can be found in member T0011INF in 
source file QATTINFO in library QUSRTOOL. 
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Chapter 17. Details of Using User Interface Manager 


This chapter explains the structure of the OS/400 user interface manager (UIM) and 
provides an overview of its objects and functions. 


Opening a UIM Application 


An application program must first open a UIM application that uses the panel group 
to access dialog variables, lists, and panel definitions. An application is opened by 
the Open Display Application (QUIOPNDA) or Open Print Application (QUIOPNPA) 
APIs and closed by the Close Application (QUICLOA) API. A UIM application is 
managed much like an open file. It is meaningful only for a particular call for 
reclaim resources processing, and it is automatically closed as necessary by the 
reclaim resources function or by cleanup processing at the end of a job. 


When an application is opened, UIM assigns each application an application 
handle. A handle is a variable that represents an object, an instance of an applica- 
tion using some function, or a processing session. This handle must be specified 
as an input parameter to all APIs that operate with the application. The same 
panel group object can be associated with more than one open application in the 
same job, but each application contains a completely independent set of dialog var- 
iables, active lists, and internal control information that define the state of the UIM 
application. 


Defining Dialog Variables 
A dialog variable is a UIM element that contains a value. This value can be 
referred to and updated by programs that use the open application and by the UIM 
when it performs functions such as displaying panels to the user. 


The dialog variables contained in an open application are determined by the panel 
group object associated with the application. Dialog variables are defined using the 
variable definition (VAR) language tag in the source for a panel group. Special 
dialog variables defined by UIM have names that begin with the letter Z and are 
referred to as Z-variables. For more information on the VAR language tag, see 
“VAR (Variable Definition)” on page A-166. For more information on Z-variables, 
see “Dialog Variables Defined by UIM” on page A-166. 


Every open application associated with a particular panel group object contains a 
complete set of all the dialog variables defined in the panel group, including what- 
ever Z-variables are defined in the tag language for that panel group. The set of all 
dialog variables in an application is called the variable pool for the application. 
UIM is not able to communicate directly with a program's storage to get the values 
of its variables. The program can use the variable pool to communicate to UIM 
what it would like to display on the panel. When a panel is to be displayed, UIM 
retrieves the values from the variable pool and displays them on the panel. When 
the user updates the fields on the panel, UIM reads the values from the panel and 
places them into the variable pool for the user program to retrieve and act upon. 
Because each open application has its own variable pool, each time a user 
program wishes to gain access to the dialog variables in an application, it must 
provide the variable pool APIs with the application handle that was assigned by the 
QUIOPNDA API. 
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For more information on variable pools, see “Using Variable Pool Services” on 
page 17-4. The dialog variables are used to display panel field values that are not 
constant text. The dialog variables are also used to tailor the format of the panel 
using the condition definition (COND) tag. For more information on the COND tag, 
see “COND (Condition Definition)” on page A-27. 


The definition of each dialog variable specifies a base data type value that controls 
both the form of the internal storage of the variable and its editing characteristics on 
the display. The following base type values are supported: 


e Character 

« IGC 

¢ Graphic 

¢ Binary (numeric) 

e Packed and zoned decimal 
¢ Date 

e Time 

¢ Action (list option or selection) 
e Name 

¢ Object name 

e Pointer 


The class definition (CLASS) language tag defines a class of dialog variables to be 
associated with a base data type, specific validity checking, and display value 
translation functions. Validity checking is done only for values entered by the user 
in an input field on a display. The validity checking is not done for values provided 
by an application program through an API. For more information on the CLASS 
tag, see “CLASS (Class Definition)” on page A-14. 


A translation function allows the application program to operate with internal values. 
The values are automatically mapped by the UIM to and from specified character 
string values, when displayed or printed. An example of this is the months in a 
year. The application program reference the values 1 through 12, but the user 
sees only the names of the months on the display. For more information on the 
translation function, see “TL (Translation List)” on page A-159. 


When the application is initially opened, every dialog variable in the application has 
an initial value. For dialog variables defined by the application programmer, the 
initial value is determined by the base type as follows: 


Table 17-1. Initial Values of Dialog Variable 


Dialog Variable Initial Value 

Numeric 0 

Date and Time 0 

Character Single-byte blanks 

IGC Single-byte blanks 

Graphic Double-byte blanks 

Pointer Null 

Z-variable Defined by the definition of the variable (see “Defining 


Dialog Variables” on page 17-1) 
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Any dialog variable that is referenced without a set value is assigned the initial 
value, whether the reference is made by an application program or by the UIM. 


Restrictions on Using Dialog Variables 


A dialog variable should not be used for the value of more than one display item 
per panel as multiple input fields, because the results might be undesirable. This 
means that when used as input fields, no dialog variable should be named on mul- 
tiple data item (DATAI), data item extender (DATAIX), or list column (LISTCOL) 
tags that are part of the same panel definition without conditioning. This ensures 
that the same dialog variable does not appear on the display in more than one 
place. 


Because the variable pool exists until the application is closed, the UIM, and all 
programs that use the application, can determine the last value assigned to any 
dialog variable in the pool. Once the application program assigns the value of a 
dialog variable, it never needs to be assigned again as long as it does not need to 
be changed. Similarly, once an input value is accepted from the user and stored in 
a dialog variable, that value continues to be available until the variable is updated 
by either an application program or the user. 


Dialog Variable Error Messages 
By defining a variable of basetype char 1 on the ERRVAR attribute of the VAR tag, 
the user may indicate to UIM that a variable is in error by using the Put Dialog 
Variable (QUIPUTV) API to set this variable to (X“F1”). When this happens, the 
field in error is highlighted and the cursor is positioned to the first input field that is 
in error. The application program reports the cause of the error and requests that 
the UIM display the messages to the user using the message reference key param- 
eter of the Display Panel (QUIDSPP) API. 


All variables in error in the open application are reset when the next dialog 
command is processed by the UIM. Exceptions to this are the Menu Bar Cursor 
Action (ACTIONS), Command Line (CMDLINE), Change View (CHGVIEW), HELP, 
Display More Function Keys (MOREKEYS), Move to Top (MOVETOP), PAGEUP, 
PAGEDOWN, Print Screen (PRINT), and Retrieve Command String (RETRIEVE) 
dialog commands. The error status for each dialog variable is reset when control 
returns from the Display Panel (QUIDSPP) API or when control is passed from the 
UIM to a program or command identified by a menu item, action list, pull-down 
choice, or function key item. 


When a function key is pressed or a pull-down choice is selected that performs an 
action where VARUPD=YES was specified, ((see “KEYI (Key List Item)” on 

page A-74), and “PDFLDC (Pull-Down Field Choice)” on page A-134), the UIM val- 
idates the values of all entered (changed) input fields. If an error is found, the 
panel is displayed again with the fields in error highlighted and one or more mes- 
sages is issued. The values of the dialog variable associated with the input fields 
are not changed until the user enters a correct value. 


The application developer can specify that some function keys and pull-down 
choices operate without updating the variable pool by using VARUPD=NO. If 
control returns to the program that ran the QUIDSPP API for such a function, all 
values entered by the user are lost. If the requested function causes the UIM to 
call a program or system command, all input field values are stored internally by 
the UIM in such a way that they can be shown when control returns to the UIM and 
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the panel is displayed again. These input values are stored locally for the panel 
being displayed. Any panel that is presented using the same open application by a 
program or command with VARUPD=NO specified, displays the values of all dialog 
variables as they exist in the variable pool. However, if VARUPD=YES is specified, 
the updated value is used instead of the stored value when control returns and the 
original panel is displayed again. 


Providing Field Values for a Display Panel Using Dialog Variables 


Using Variable 


The tag language allows you to use dialog variables to provide field values for a 
display panel and substitution values for a CL command that is called by the UIM 
for a pull-down choice, menu choice, function key, or action list selection. When- 
ever a dialog variable is referred to in one of these ways, the internal value stored 
in the variable pool is converted to an external form determined by the editing rules 
for the variable base type and any translation list defined for the variable class. 


When the external form of a dialog variable contains characters that are incorrect 
for a display device, the UIM converts the incorrect characters to hexadecimal 1F 
characters ( [J ). When the external form of a dialog variable contains characters 
that are incorrect for a printer, the UIM converts the incorrect characters to the 
replacement characters in effect for the printer file, or to blanks when 
RPLUNPRT(*NO) is in effect for the printer file. 


Incorrect display characters are characters with hexadecimal values equal to 
hexadecimal FF or less than 40, not including hexadecimal 00, OE, and OF. Incor- 
rect printer characters are the same as the incorrect display characters, except that 
hexadecimal 00 is also incorrect. This conversion does not take place on variable 
values that have been translated with a translation list. 


If the dialog variable that contained the incorrect characters is used as an input 
field and retrieved with the Get Dialog Variable (QUIGETV) API by the program, the 
incorrect characters might be changed to hexadecimal 3F. This occurs if the user 
modifies the field or presses the Help key. 


When the UIM displays a panel, it retrieves the current value for all variable fields 
from the variable pool or from list entries. If the user types a value in an input field, 
the UIM validates and translates the value according to the CLASS attribute of the 
associated dialog variable, and then stores the value in the dialog variable or asso- 
ciated list entry. The application program can determine the value entered by the 
user by using the Get Dialog Variable (QUIGETV) or the Get List Entry 
(QUIGETLE) API to retrieve the dialog variable value. 


Pool Services 


The Get Dialog Variable (QUIGETV) and Put Dialog Variable (QUIPUTV) APIs are 
the primary interfaces for application programs to retrieve and update dialog vari- 
ables. When a dialog variable is updated, the attributes of the new value must 
match the base type of the dialog variable. When a dialog variable is retrieved, the 
value is always returned to the application program in the internal form specified by 
the base type of the dialog variable. On the call to the variable pool services APIs, 
a variable record is required. A variable record, defined using the VARRCD tag in 
the UIM panel group source, defines a group of dialog variables that may be 
updated or accessed together in one call to the APIs. 
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No data conversion or validity checking is done when variable values are retrieved 
or updated using the QUIGETV and QUIPUTV APIs. For more information on 
these APIs, see the System API Reference. 


Some of the dialog variables defined by UIM, referred to as Z-variables, can be 
retrieved but not modified. The tag language does not allow a variable with only 
read access to be used as an input field on a panel definition. The UIM returns an 
exception to an application program if it attempts to update such a Z-variable using 
the QUIPUTV API. 


Character Set and Code Page Considerations 


Data that is always stored in a specific character set and code page can be con- 
verted to another character set and code page when it is displayed or printed by 
the UIM. If your application has data that must be converted, do one the following: 


¢ Code CHRID=PNLGRP on the CLASS tag of the variables that need to be con- 
verted. See “CLASS (Class Definition)” on page A-14. Then, specify the 
number of the graphic character set and code page of your data on the CHRID 
parameter of the Create Panel Group (CRTPNLGRP) command that is used to 
create your panel. For more information on the CRTPNLGRP command, see 
the CL Programming book. 


¢ On the CHRID parameter of the Create Panel Group (CRTPNLGRP) command 
that is used to create your panel, specify *JOBCCSID. For more information on 
the CRTPNLGRP command, see the CL Programming book. 


Displaying 

The UIM compares the character set and code page of the device to the character 
set and code page of the panel group. If they are different, then outbound and 
inbound conversion tables are used to convert the appropriate dialog variables. Ifa 
conversion table is not available, then the Open Display Application (QUIOPNDA) 
API sends a diagnostic message and continues. 


Display operations for Arabic and Hebrew bidirectional panel groups, which have 
BIDI=LTR or BIDI=RTL specified on the panel group (PNLGRP) tag, are only 
allowed when the device is configured to use code page 420 or 424. 


See Table 17-2 for a summary of how CCSIDs are converted. 


Table 17-2. UIM CCSID/CHRID Conversions for Display 
Panel Group CHRID 


Type of Data XXX *JOBCCSID *DEVD 
Panel group constant No conversion. Convert from No conversion. 
text panel group 

primary source 

file CCSID to 

device CCSID. 


Variable with 
CHRID=PNLGRP on 
CLASS tag 


Convert from 
XXX to device 
CHRID. 


Convert from job 
CCSID to device 
CCSID. 


No conversion. 


Variable without 
CHRID=PNLGRP on 
CLASS tag 


No conversion. 


Convert from job 
CCSID to device 
CCSID. 


No conversion. 
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Printing 

The UIM compares the character set and code page of the printer file to the char- 
acter set and code page of the panel group. If they are different, an outbound 
conversion table is used to translate the appropriate dialog variables. If 
CHRID(*DEVD) is specified for either the panel group or the printer file, no conver- 
sion of the dialog variables is done. If a translation table is not available, the Open 
Display Application (QUIOPNDA) or the Add Print Application (QUIADDPA) API 
sends a diagnostic message and continues. 


When a printer file is printed on a printer device, the character set and code page 
of the printer file is compared to the character set and code page that is loaded in 
the printer. If they are different, all the printer file data, including the constant text 
from the UIM tags, is translated to the character set and code page of the printer. 


To minimize the number of times that character set and code page translations 
takes place, specify the same CHRID value on both your printer file and your panel 
group. 


Print operations for Arabic and Hebrew bidirectional panel groups, which have 
BIDI=LTR or BIDI=RTL specified on the panel group (PNLGRP) tag, must have 
code page 420 or 424 specified for the printer file. Also, any call to the QUIADDPA 
API for a bidirectional panel group must have the same code page specified for the 
printer file as is used by the display device. 


See Table 17-3 on page 17-7 for a summary of how CCSIDs are converted. 
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Table 17-3. UIM CCSID/CHRID Conversions for Print 


Panel Group CHRID or Menu CHRID 


Print File 
CHRID XXX *JOBCCSID *DEVD 
YYY Panel group constant text: Panel group constant text: Panel group constant text: 
no conversion. convert from panel group no conversion. 
primary source file CCSID to 
YYY. 
Variables with Variables with Variables with 
CHRID=PNLGRP on CLASS | CHRID=PNLGRP on CLASS | CHRID=PNLGRP on 
tag: convert from XXX to tag: convert from job CCSID CLASS tag: no conversion. 
YYY. to YYY. 
Variables without Variables without Variables without 
CHRID=PNLGRP on CLASS | CHRID=PNLGRP on CLASS | CHRID=PNLGRP on 
tag: no conversion. tag: convert from job CCSID CLASS tag: no conversion. 
to YYY. 
*JOBCCSID Panel group constant text: Panel group constant text: Panel group constant text: 
no conversion. convert from panel group convert from panel group 
primary source file CCSID to primary source file CCSID 
job CCSID. to job CCSID. 
Variables with Variables with Variables with 
CHRID=PNLGRP on CLASS | CHRID=PNLGRP on CLASS | CHRID=PNLGRP on 
tag: convert from XXX to job tag: no conversion. CLASS tag: no conversion. 
CCSID. 
Variables without Variables without Variables without 
CHRID=PNLGRP on CLASS | CHRID=PNLGRP on CLASS | CHRID=PNLGRP on 
tag: no conversion. tag: no conversion. CLASS tag: no conversion. 
*DEVD Panel group constant text: Panel group constant text: Panel group constant text: 


no conversion. 


convert from panel group 
primary source file CCSID to 
job CCSID since variables 
are in job CCSID and device 
CCSID is unknown. 


no conversion. 


Variables with 
CHRID=PNLGRP on CLASS 
tag: no conversion. 


Variables with 
CHRID=PNLGRP on CLASS 
tag: no conversion. 


Variables with 
CHRID=PNLGRP on 
CLASS tag: no conversion. 


Variables without 
CHRID=PNLGRP on CLASS 
tag: no conversion. 


Variables without 
CHRID=PNLGRP on CLASS 
tag: no conversion. 


Variables without 
CHRID=PNLGRP on 
CLASS tag: no conversion. 


Managing a List 


A UIM list is a sequential set of list entries. Each entry contains a copy of the 
value for one or more dialog variables. The entries in a list can be presented to the 
user in a scrollable area of a display. The UIM provides application programming 
interfaces (API) that allow an application program to perform the following oper- 


ations on lists: 


e Add anew entry between any two entries in the list. 


e Add an entry at the beginning or end of the list. 
e Update the values in a list entry. 


e Remove a list entry. 
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e Position the current entry pointer for the list to a specific entry; several position 
options are available. 

¢ Set and retrieve list attributes that control UIM processing when the list is dis- 
played. 

e Delete an active list. (Remove all entries from a list and make the list inactive 
for the application.) 


Defining a List 
The definition for each list using the list definition (LISTDEF) language tag is speci- 
fied in the source for the panel group object. Attributes of the list definition 
(LISTDEF) tag specify the name of the list and what dialog variables should be 
associated with the list (that is, what variable values are to be stored in each list 
entry). For more information on the LISTDEF tag, see “LISTDEF (List Definition)” 
on page A-100. 


Each entry in a list contains a copy of the values of all dialog variables associated 
with the list. The values of the dialog variable are copied into a list entry when the 
entry is first added to the list using the Add List Entry (QUIADDLE) or Add List 
Multiple Entries (QUIADDLM) API, and whenever the entry is updated using the 
Update List Entry (QUIUPDLE) API. The values in a list entry can be copied into 
the corresponding dialog variables when the entry is retrieved using the Get List 
Entry (QUIGETLE) or Get List Multiple Entries (QUIGETLM) API. 


Initializing a List 
All UIM APIs for processing lists require the program to specify the list name on the 
list object definition (LISTDEF) tag in order to identify the target list for the opera- 
tion. Each list defined in a panel group is either active or inactive for each open 
application using the panel group. Each list is initially inactive when an application 
is opened using the Open Display Application (QUIOPNDA) or Open Print Applica- 
tion (QUIOPNPA) API. A list becomes inactive when it is deleted using the Delete 
List (QUIDLTL) API. A list may be active in multiple different open applications 
using the same panel group. A list becomes active when the first entry is added to 
the list using the Add List Entry (QUIADDLE), or Add List Multiple Entries 
(QUIADDLM) API, or when the list attributes are set using the Set List Attribute 
(QUISETLA) API. The maximum size of a list is approximately 16MB. The 
maximum number of entries that can be added to a list is based on the size of 
each entry. 


Displaying a List 
When a panel containing a list area is displayed, entries from the list are used to 
build a display area that appears to the user as a table. Each list area is associ- 
ated with one list definition (see “LIST (List Area)” on page A-82) and contains an 
independent selection of columns to display. For more information on the LISTCOL 
language tag, see “LISTCOL (List Column)” on page A-96. A list can be referred 
to by more than one list area. The list area allows one list to be presented on 
different panels within the same open application. If more than one list area exists 
in a panel definition, a different list must be used for each list area. 


Use the LISTCOL tag to specify the specific values presented in a list area. A list 


area can present all the values in the associated list entries, or it can present only 
a subset of the values available in each list entry. The list area the user sees 
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contains a row for each list entry and a column for each field specified in a 
LISTCOL tag in the definition of each view of the list area. 


You can define a list area to present the values associated with only one list entry 
per display line or with multiple list entries per display line. When multiple entries 
are shown on each display line, the display is formatted in multiple layouts with 
entries presented in order from top to bottom within layout columns, and from left to 
right between layout columns. See “Example 2: List Area with Three Layout 
Columns” on page A-87. 


Updating a List 
Values of list entries are used to fill the display for all fields in the list area; see 
“LISTCOL (List Column)” on page A-96. The user can update any input fields on 
the display, including those in the list area. If the value specified by the user satis- 
fies all validity checks for the associated dialog variable, the corresponding value in 
the list entry is updated with the value specified by the user. 


The UIM APIs provided to retrieve, add, and update list entries all operate by using 
the dialog variables associated with the list. No support is provided to directly 
establish or change values of list entries without referencing dialog variables. 
Every time a list entry is retrieved, added, or updated, the entire set of values for 
dialog variables is copied to or from the list entry. When the UIM refers to or 
updates list entries, such as processing user options in an action list, it can also 
update values of dialog variables that correspond with the list columns. 


Note: When working with an action list you should take care during incomplete list 
processing. To avoid undesirable results, the action dialog variable should 
be included in the VARRCD for the list entry and updated in the same way 
as the other variables in the variable record. If you don't do this, you run 
the risk of updating each new list entry (during incomplete list processing) 
with the value of the last option that was entered on the panel. For 
example, you have a list panel with 12 entries. You enter option “4” on one 
entry and scroll down. The incomplete list exit is called to add more entries 
to the list. The option dialog variable has a value of “4,” so each entry that 
is added may now have a “4” in the option field. 


Each entry inserted in a list is assigned an identifier, called a list entry handle, 
that uniquely identifies the entry within the active list until the entry is removed from 
the list. The identifier is meaningful only for a particular combination of open appli- 
cation, active list, and list entry instances. An identifier has no meaning in any 
other open UIM application, or even in the same application if the list or the entry is 
deleted and then created again. Undesirable results are possible if an identifier is 
used outside of this definition. 


Incomplete List Processing 


When adding entries to an action list during incomplete list processing, take care to 
ensure the option field contains the appropriate value (usually blanks) at the time 
the QUIADDLE or QUIADDLM API is called. If you are using a VARRCD, the 
option variable should be part of the VARRCD. 
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Removing and Inserting an Entry from a List 


After an entry is removed from a list, it can no longer be accessed by the applica- 

tion program, and it does not appear even as a blank line in a list area on a panel. 
When a new entry is added to a list, the UIM can assign the same list entry handle 
for that entry that was used for an entry that was previously removed from the list. 

An identifier value has no relationship to the logical position of the entry within the 

sequence defined for the entries in the list. 


The UIM maintains a current entry pointer for each active list to use as a reference 
point for list-entry operations. The list entry manipulation APIs support a list entry 
handle parameter. This parameter returns to the application program the identifier 
where the current entry pointer for the list was positioned at the end of the opera- 
tion. The UIM sets the current entry point to: 


e The entry just added by the Add List Entry (QUIADDLE) or Add list Multiple 
Entries (QUIADDLM) API 


e The list entry requested by the Get List Entry (QUIGETLE) or Get List Multiple 
Entries (QUIGETLM) API, or left unchanged if the requested entry is not found 
or not available 


e The entry that preceded the entry removed by the Remove List Entry 
(QUIRMVLE) API 


The current entry point is unchanged by the Update List Entry (QUIUPDLE) API. 


The Get List Entry (QUIGETLE), Get List Multiple Entries (QUIGETLM), and 
Remove List Entry (QUIRMVLE) APls may set the current entry pointer position to 
either the top or bottom of the list. The top is the position that is always logically 
before the first entry in the list, and the bottom is the position that is always log- 
ically after the last entry in the list. Each of these positions has a special identifier 
value for the list entry handle, but because the top and bottom are not "real" 
entries, they cannot be updated or removed from the list. The application program 
receives an error if it attempts to insert an entry before the top of the list or after 
the bottom of the list. 


Controlling List Entries on a List Display 


The application program can control what list entry appears as the topmost entry in 
a list area on a panel by setting the display position attribute to a valid list entry 
handle before the Display Panel (QUIDSPP) API is run. For example, this function 
can be used to position to a particular list entry specified by the user. When the 
display position attribute is not set by the Set List Attributes (QUISETLA) API 
between the time the list is initialized and the first time the list is displayed, the UIM 
presents the first entry at the top of the list area in the panel. For more information 
on the Display Panel (QUIDSPP) API, see the System API Reference. 


The display position attribute is updated whenever the user moves to a new page 
of the list. Any time the application program removes the entry identified by the 
display position attribute, the display position attribute is automatically updated to 
refer to the entry preceding the one removed. If there is no entry before the one 
removed, the display position attribute is set to the top of the list, and the next 
display of the panel presents the first entry at the top of the list area in the panel. 


When an entry is added or updated in a list, the error state of every dialog variable 
associated with the list is saved with the list entry. The processing described in 
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“Defining Dialog Variables” on page 17-1 for dialog variables in error state is also 
used for list entry values that are in error state. This processing concerns how 
validation errors are detected by the UIM and how the VARUPD attribute of the key 
item (KEYI) and pull-down field choice (PDFLDC) tags affects updating list values. 


Improving Interactive Response Time for a List Display 
To improve interactive response for a list display, the UIM list processing allows an 
application program (the incomplete list exit program) to build only part of a list 
before it is shown to the user. Because the UIM handles scrolling lists as part of 
displaying a panel, without returning to the program that ran the Display Panel 
(QUIDSPP) API, the application program must tell the UIM whether the entries in 
the list represent only the top, middle, or bottom part of the complete list. If the 
program calls the Set List Attribute (QUISETLA) API to set the list contents attribute 
to a value other than ALL, and if the user attempts to page to list entries that are 
available to the application but not yet added to the list, the UIM calls an application 
program to add more list entries. The application program is also called by the UIM 
as part of Get List Entry (QUIGETLE) or Get List Multiple Entries (QUIGETLM) API 
processing if the specified entry is not found but might exist in the part of the list 
that has not yet been added. 


When a panel is displayed that contains a list area and the associated list is either 
not active or contains no entries, the user sees a blank list area and a message 
indicates that there are no entries in the list. However, if the list attributes are set 
to indicate that the list is not complete, an application program is called to add 
entries to the list. The panel is not displayed to the user until either enough entries 
are added to the list to present a full display page or the application program marks 
the list as complete at either the top or the bottom. The application program is 
called not only when the list is empty but any time there are not enough entries in 
an incomplete list to fill a list area on the panel. 


Using Action Lists and Selection Lists 
The UIM supports the following types of lists: 


¢ Action list 

¢ Selection list 

¢ Output only list 
e Input/output list 


Using Action Lists 

An action list is a list area where the user can type option numbers to perform 
actions against one or more entries in the list. The definition of the UIM list dis- 
played as an action list must include a variable defined with BASETYPE=ACTION 
specified on the CLASS tag. This variable is referred to as the action variable of 
the list. 


To define an action list area, the application developer must specify ACTOR=UIM or 
ACTOR=CALLER on the LIST tag. In addition, one LISTACT tag must be defined for 
each option number that can be entered by the user. 


For an ACTOR=UIM action list, each LISTACT tag specifies the action the UIM per- 
forms when the user types the option number and presses the Enter key. The 
application developer can also define an action the UIM performs when the user 
presses a key assigned to the PROMPT dialog command. Two types of actions 
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can be performed: run a CL command, or call a program. If the action to be per- 
formed is to run a CL command, an action-list exit program might be needed to 
update the list after the CL command has performed the function for the option. No 
interface between UIM and a CL command allows the program called by the CL 
command to obtain the application handle. Therefore, if the program called by the 
CL command performs a change or delete operation, an action-list exit program is 
required to update the list. 


For an ACTOR=CALLER action list, there is no specification of an action. When the 
user types the option number and presses the Enter key or a function key assigned 
to the PROMPT dialog command, the UIM returns control to the application 
program. The function requested parameter contains a value which indicates that 
the application program should perform the actions associated with the options 
selected by the user. 


Having the UIM as the actor for the action list is the preferred method because of 
the following benefits: 


e¢ The UIM performs all actions entered by the user. 


e¢ The UIM automatically displays a confirmation panel for destructive actions, 
such as option 4 to delete an object. No application program code needs to be 
written to provide confirmation support. 


e¢ The UIM redisplays the action list panel in cases where an action does not 
complete successfully. When the UIM receives an escape message, the UIM 
redisplays the list with the cursor located on the option number. The option 
number is shown in error. When the Exit (F3) or Cancel (F12) function is 
requested from a panel displayed as a result of the list option, the UIM redis- 
plays the panel as appropriate. For more information about the UIM processing 
a request for Exit and Cancel when displaying an action list, see “Folding Up a 
List Panel” on page 17-26. 


When the application program is the actor for an action list, the above processing 
must be done by the application program. 


When a panel contains an action list and a menu bar, pull-down choices can be 
defined within the menu bar which operate against each selected entry in the action 
list. When at least one pull-down choice is defined which operates against selected 
list entries, the UIM allows the user to select entries by typing a valid selection 
character. The user selects one or more entries in the list, selects a pull-down 
menu from the menu bar, and then selects a choice from the pull-down menu. The 
UIM performs the selected pull-down choice for each entry selected by the user. 


Using Selection Lists 

A selection list is a list area in which the user can type a selection character for 
one or more entries in the list. A selection list is defined to allow the user to select 
a single entry or multiple entries in the list. 


A selection list can be used for the following purposes: 


e Allow the user to select an object or value from a previously displayed entry 
field. This type of selection list is displayed when the user positions the cursor 
to an entry field and requests the PROMPT dialog command. The F4 key is 
recommended to be assigned to the PROMPT dialog command. 
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e Allow the user to select entries and then perform an action defined in a pull- 
down menu from the menu bar. 


The definition of the UIM list displayed as a selection list must include a variable 
defined with BASETYPE=ACTION specified on the CLASS tag. This variable is 
referred to as the action variable of the list. When the user enters a valid 
selection character for a list entry, the UIM sets the action variable for that entry to 
1000. A value of 1000 for an action variable always indicates that the list entry is 
selected. 


When a panel contains a selection list and a menu bar, pull-down choices can be 
defined within the menu bar which operate against each selected entry in the list. 
The user selects one or more entries in the list, selects a pull-down menu from the 
menu bar, and then selects a choice from the pull-down menu. The UIM performs 
the selected pull-down choice for each entry selected by the user. 


Using Selection Characters 


The user selects entries in an action list panel that contains a menu bar or a 
selection list panel by typing a slash (/), or country-designated selection character, 
in the option or selection field for the desired list entries. The country-designated 
selection character is determined for each panel group when the panel group is 
created. The UIM retrieves the first level text of message CPX5A0C in the CCSID 
of the panel group source file. The first two characters of this message are stored 
in the panel group object. These characters are the allowed uppercase and lower- 
case country-designated selection characters for selection lists and multiple-choice 
selection fields defined in the panel group. 


If *“JOBCCSID is specified for the CHRID attribute when the panel group is created, 
the country- designated selection characters are converted at run time from the 
panel group source file CCSID to the job CCSID. This enables the comparison to 
be done in an equivalent CCSID. 


Managing Panel Functions 
The UIM supports the following panel management functions: 


e Enabling panel conversion to a graphical user interface (GUI) 
¢ Scrolling 

e Limiting user capabilities 

¢ Defining contextual help 

¢ Command line restrictions 

¢ Defining function keys 

e¢ Formatting panels 

¢ Folding up panels when exit is requested 

e Folding up list panels 

e UIM as a request processor when displaying a panel 


All operations performed by the UIM are done in a single process called a routing 
step. It is the application developer's responsibility to consider the effects of things 
such as recursion, locks, and static storage, for each of the following functions: 


e Function key action 
e Menu or action list option 
e Pull-down choice 
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e Exit program 
¢ Command entered by the user on a command line 


The UIM does not guarantee that the call-sensitive effects of programs and CL 
commands, such as overrides and the Set Attention Program (SETATNPGM) 
command, are preserved when commands are run from a panel in any of the ways 
listed above. The effect of any command that scopes its function to the program 
call that used the command might be lost by the time the next command or 
program is called. This is because the UIM call to the function that was scoped was 
destroyed in the interim. 


Enabling Conversion to a GUI 


The UIM supports encoding information in the panel which allows a client program 
to convert your panels to a graphical user interface (GUI). 


You can use the ENBGUI attribute on the PANEL or PNLGRP tag to specify 
whether you want the encoded information included in your panels. More informa- 
tion on how to set this attribute can be found in “PANEL (Display Panel)” on 

page A-122 and “PNLGRP (Panel Group)” on page A-139. 


Scrolling Support 


The UIM supports page up and page down scrolling of all panel information, data 
presentation, list, and menu areas. Multiple scrollable areas can be defined on a 
single panel; the UIM imposes no order on them. However, using scrollable menus 
is discouraged because of usability. 


No left-to-right scrolling of text is provided, but the Change View (CHGVIEW) dialog 
command for lists can be used to show more fields. 


Defining Scrollable Areas 


To use the UIM scroll function, the panel must have at least one scrollable area 
and have function keys defined to perform the PAGEUP and PAGEDOWN dialog 
commands. For more information on the PAGEUP and PAGEDOWN dialog com- 
mands, see Appendix B, “UIM Dialog Commands” on page B-1. 


Panels with scrollable areas must have function keys assigned to the PAGEUP and 
PAGEDOWN dialog commands because the UIM does not automatically enable 
any function keys. Normally these are the Page Up and Page Down keys,' but if 
you use a function key, F7 and F8 are recommended. The UIM does not prevent 
assigning different function keys to the PAGEUP and PAGEDOWN dialog com- 
mands, but it does not allow assigning the engraved page keys to anything other 
than their implied functions which is page up and page down. 


Scrolling status information is also managed by the UIM and is displayed at the 
bottom of each scrollable area. 


The message line is under UIM control. A plus sign (+) on the message line indi- 
cates that more messages can be viewed by pressing the Page Down key. 


1 On a 5250 keyboard, these are the Rolldown and Rollup keys respectively. 
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Because you can scroll a message area, the function keys for scrolling should 
always be defined. 


Defining Function Key Scrolling 


The UIM handles all scroll- and page-key functions for UlM-defined panels; these 
functions cannot be overridden by the application. However, you can define other 
function keys that work much like scroll keys. 


When a function key assigned to the PAGEUP or PAGEDOWN dialog command is 
pressed, the UIM scrolls the appropriate amount for the panel type. This is always 
a "page," but the UIM tries to avoid having data item groups, menu item groups, 
and selection fields split across page boundaries. 


The position of the cursor determines which area to scroll. If the cursor is not ina 
scrollable area (except for a pull-down menu), the scroll request applies to the 
topmost scrollable area on the display. If the cursor is in a scrollable area, the 
scroll request applies to that area. The bounds of the scrollable area are the top 
and bottom line of that area as defined by the menu area (MENU), data presenta- 
tion area (DATA), list area (LIST), and information area (INFO) language tags. For 
more information on these language tags, see Appendix A, “UIM Panel Group Defi- 
nition Language” on page A-1. Titles and instruction lines are part of the area but 
not part of the scrollable portion of the area. 


The command line is not considered part of a scrollable area, but it may be associ- 
ated with a particular area on the screen. For example, a panel with a scrollable 
menu area has a command line and it is associated with the menu. However, for 
scrolling purposes, the command line is not part of the area. 


Scrolling and Error Conditions 


The message line always exists and is always the last scrollable area on the 
screen so the scroll function keys must always be active. 


When scrolling the message line, the UIM does not perform any validity checking or 
updating of the dialog variables. When scrolling any other area, validity checking or 
updating of the dialog variables is performed on all input fields on the screen. The 
scroll function is not performed if an error is found. All input and output fields on 
the screen must be correct before the scroll operation can proceed. 


If a page key is pressed and the operation cannot be performed, a message is 
displayed. For example, a message is shown if a display is already at the top 
when the Page Up key is pressed. The alarm sounds when trying to scroll the 
message line past its top or bottom. 


Scrolling a List Area 


List processing allows an incomplete list to be displayed. If the Page Down key is 
pressed and the remainder of the incomplete list does not fill the list area, the UIM 
calls the specified application program that handles incomplete lists. This program 
adds additional entries to the list or marks the list as complete at the bottom, then 
the program returns to the UIM. The UIM knows an incomplete list by the setting of 
the contents attribute of lists on the Set List Attributes (QUISETLA) API. Once the 
list is complete, the UIM handles scrolling without application program intervention. 
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A list might be incomplete at both the top and bottom. If a list has missing informa- 
tion above the current location, pressing the Page Up key causes the same type of 
processing. 


Scrolling a Menu Area 
The UIM attempts to keep menu item groups together but splits the group if it does 
not fit in the defined area. Any individual menu item or text for a menu group must 
fit within the available scrollable space or the panel group is not created success- 
fully. 


Scrolling an Information Area 
Using the Move to Top (MOVETOP) dialog command moves a cursor-selected line 
to the top of the scrollable information area. This allows the user to position the 
information in the most readable manner. For more information on the MOVETOP 
dialog command, see “MOVETOP (Move to Top)” on page B-11. 


Scrolling Data Item Groups 
The UIM keeps data item groups together if possible. A group is split only if it does 
not fit within a column of the data area. When a data item group is nested inside 
another data item group and the outer group must be split, the UIM still attempts to 
keep the inner groups together. If a selection field does not fit in a column of the 
data area, the panel group is not created. 


Data presentation areas can also be presented in multiple columns and the 
columns are filled from left to right. Generally, scrollable data presentation areas 
should not be defined with a two-column layout because the usability is poor. 


Scrolling a Text Area 
Scrolling for a text area must be handled by the text area exit program. UIM does 
not handle scrolling for text areas. When a key assigned to a scrolling dialog 
command is pressed and the text area should be scrolled, UIM calls the text area 
exit program. On return, the UIM redisplays the panel. The text area exit program 
should change the value of the dialog variable for the text area in order to scroll the 
text area. 


A general panel exit program should be used to diagnose if the user has scrolled 
too far. If the user has scrolled too far, the general panel exit should send an 
appropriate message followed by the special message to cancel the determined 
action. For the message to cancel the determined action, see the section on the 
general panel exit program in the System API Reference. 


Defining Contextual Help 


Contextual help is provided jointly by the UIM and the system help function. Using 
the tag language, a panel is defined to associate help modules with different areas 
on the screen. When the Help key is pressed, the UIM determines which help 
modules to display. 


When defining a panel, the user can associate help text with the following areas: 


e Entire panel 
e Menu bar 
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e Menu bar choice 

e Pull-down field choice 

¢ Specific menu item 

e Specific data item 

¢ Specific data selection field 

¢ Choice for data selection field 
¢ Specific list column 

e List column group 

¢ Specific function key 

¢ Specific option in an action list 
e Data group 

e Data area 


When the Help key is pressed, the UIM displays the help text depending primarily 
on where the cursor is. The rules are as follows: 


Chapter 17. Details of Using User Interface Manager 17-17 


Cursor Position 


Help Selection Rules 


On a menu item 


Help for that menu item is displayed. 


In a list column 


Help for that column is displayed. 


The left and right boundaries of a column are defined by the left and right edge of the 
field or heading, whichever is greater, plus one blank on either side. The top and 
bottom boundaries of a column are defined by the first line of the heading or column 
group heading and the last line where a list entry may be displayed. 


Help can be associated with a list column group rather than the individual entries. In 
this case, positioning within the group gives help for the entire group regardless of the 
specific column the cursor is in. Boundaries of column groups are defined by the sum 
of the individual column boundaries plus any separators between columns of the 
group. 

If the column for which help is being displayed is the option column of an action list, 
the help displayed includes the help specified for the list column and the help specified 
for each active list action. 


On any line in the function- 
key-definition area 


Help for all active function keys is displayed. 


On a message line with a 
message displayed 


Help for that message is displayed. Help for a message is provided by the Additional 
Message Information display. Help for a message does not use a help module in a 
panel group. 


On a menu bar choice 


Help for that menu bar choice and all currently active pull-down choices for that menu 
bar choice is displayed. 


On a pull-down choice 


In a pull-down input field 


Help for that pull-down choice is displayed. 


Help for the menu bar choice (see "On a menu bar choice" above) that the pull-down 


is associated with is displayed. If a valid pull-down choice is entered in the field, help 
for that pull-down choice is displayed. 


On a command line 


The displayed help depends on the contents of the command line. 


If the command line is associated with a menu area and the command line contains a 
number, help for that menu item is displayed as if the cursor were placed on that menu 
item. Help is available for any active menu item regardless of whether it is displayed. 


If the command line is assumed to contain a command, help for that command is dis- 
played. 


If the command line is being treated as a parameter line, extended panel help is dis- 
played. 


If the command line is blank, extended panel help is displayed. 


On a data item 


If help is specified for the data item, that specific help is displayed. 


If no help was specified on the data item, the data item is part of a group, and if help 
was specified at the group level, then data group help is displayed. 


If no help was specified on the item, the data item is not part of a group, or if no group 
help was specified, and help was specified on the area, then area-level help is pre- 
sented. 


On a data group heading 


The same rules apply as when the cursor is on a data item. Help is presented for the 
lowest level (group, area, or extended panel). 


In a data area 


If help is available for the area, that level of help is displayed. Otherwise, extended 
panel help is displayed. 


Any other position 


If none of the above conditions are met, extended panel help is displayed. This is true 
whenever the cursor is on the title line, any instruction line, and most blank spaces. 
Whenever there is no specific help to display, extended help is displayed. 
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Although HELP for a specific action on a list option or function key is never dis- 
played, help text is individually defined for them. This allows conditioning of active 
options and function keys. The displayed help describes only the active function 
keys or options. 


Command Line Restrictions 
The UIM allows two sizes for a command line: 


e¢ Ashort command line is one line 
e¢ A long command line is two lines 


Depending on whether the command line is short or long, the UIM formats and 
displays the command line to occupy the one or two lines preceding the function 
key area. This position remains unchanged regardless of scrolling, item condi- 
tioning, or the number of list entries. 


Command lines are defined by the command line (CMDLINE) language tag. For 
more information on the CMDLINE tag, see “CMDLINE (Command Line)” on 

page A-26. The UIM allows specifying this tag on any panel, but does not require 
it. 


When a command line is defined for a panel, it is recommended that the F4 key be 
assigned to the PROMPT dialog command and the F9 key be assigned to the 
RETRIEVE dialog command. This allows the user to prompt for commands 
entered on the command line and to retrieve previously entered commands. For 
more information on dialog commands, see Appendix B, “UIM Dialog Commands” 
on page B-1, and for more information on defining function keys, see “KEYL (Key 
List)” on page A-76. 


The UIM sometimes associates the command line with one area on the panel. Ifa 
menu area is present, the command line is associated with the menu area. If an 
action list is present, the command line is associated with the action list. If neither 
is present, the command line is not associated with an area on the panel. The UIM 
does not allow two menu areas, two action lists, or a combination of these within a 
single panel. Also, command lines and menu option lines are mutually exclusive. 
For more information on the option line (OPTLINE) tag, see “OPTLINE (Option 
Line)” on page A-120. 


Command Line Interpretation 


Command lines are used to select a menu option, to run OS/400 or System/36 
Environment commands, and to specify parameters used in conjunction with 
options on an action list. The UIM selectively interprets the character strings 
entered on the command line. 


Many dialog commands do not require any input on the command line. The fol- 
lowing conditions assume the action is one requiring the UIM to know the command 
line contents. These actions are for the ENTER, HELP, and PROMPT dialog com- 
mands. For more information on the Enter, Help, and Prompt functions, see 
Appendix B, “UIM Dialog Commands” on page B-1. 


e¢ For a command line associated with a menu, the UIM examines the first non- 
blank set of characters. If it is composed of only digits (hexadecimal FO 
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through F9), the command line is assumed to select a menu item. Otherwise, 
the command line is treated as containing a command. 


¢ For a command line associated with an action list, the command line is 
assumed to contain parameters if any option is selected on any action list 
entry. Otherwise, the command line is treated as if it contains a command. 


e¢ For a command line associated with a panel that contains neither a menu nor 
an action list, the command line is always assumed to contain a command. 


Exactly what function is performed next depends on what function key is 
pressed. For details, see the descriptions of the ENTER, HELP, and PROMPT 
dialog commands. 


Entering Commands That Are Too Long 


Commands that are too long for the command line can still be submitted by 
prompting for them. If the command causes an exception, the command line is 
displayed with the current command contents. If the full command string is too long 
for the command line, the display shows as much as possible and replaces the last 
three characters on the displayed command line with ellipses (...) to indicate contin- 
uation. The UIM still maintains the full command string internally. 


Any changes to the command line causes the UIM to discard the internal version 
and treat the changed command line as a new request. If no change is made and 
the command is prompted or submitted, the internal version is not reset and is sub- 
mitted as the new command string. Modification is based on a character compar- 
ison of the command line contents. 


Defining Function Keys 


The UIM does not automatically enable function keys; the application developer is 
responsible for enabling the correct set of function keys and ensuring that the 
correct functions are assigned to each. Function keys are defined with the key list 
(KEYL) and key list item (KEYI) language tags. For more information on these 
language tags, see Appendix A, “UIM Panel Group Definition Language” on 

page A-1. The UIM requires that engraved keys be assigned to their dialog 
command equivalent. The Help, Enter, Page Up, Page Down, Print, and Home 
keys must be assigned their respective dialog commands. With the exception of 
the PRINT dialog command, this does not prevent assigning these dialog com- 
mands to other keys as well. For example, it is recommended that the HELP 
dialog command be assigned to the F1 key as well as the Help key. The PRINT 
dialog command can be assigned only to the Print key and cannot be conditioned. 


F1 through F24 can be assigned to any of the dialog commands except PRINT and 
MOREKEYS. The MOREKEYS dialog command can be assigned only to F24. 


Formatting Function Keys 


When a panel is created, the UIM determines the worst-case display of function 
keys and their descriptions and then allocates one or two lines accordingly. Two 
lines is the maximum amount of room available to display function keys. Then this 
space is fixed. For example, if the UIM determines that two lines are required for a 
specific set of conditions, then two lines are always used, even if some conditions 
cause only one line of description for the function keys. 
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Handling Function Keys and VARUPD Value 


The dialog command assigned to a function key determines the function of that 
particular key. For more information on handling function keys, see Appendix B, 
“UIM Dialog Commands” on page B-1. 


Function keys that are inactive due to conditioning are treated as if they are not 
defined. If the user presses a function key that is not defined, a message is dis- 
played to indicate that the key is not allowed. When help is displayed for the func- 
tion key area, no help information is displayed for inactive keys. 


When defining a function key, the VARUPD attribute of the key list item (KEYI) or 
pull-down field choice (PDFLDC) language tag defines whether dialog variables and 
list entry values should be updated with user entered values when the function key 
is pressed or when the pull-down choice is selected. If any fields on the panel fail 
validity checking, the action associated with the function key or pull-down choice is 
not performed. 


Although most dialog commands have a predefined, unchangeable value for 
VARUPD, some dialog commands do not. When a function key is assigned to one 
of these dialog commands, processing of that request depends on the value of 
VARUPD. 


When VARUPD=YES is specified, all values keyed in by the user must pass 
validity checks. If any values fail the validity checks, the following occurs: 


e Any dialog variable that does not pass validity checking is not updated. 
e The specified function is not performed. 
e The general exit program for the panel, if specified, is not called. 


e The UIM displays the same panel again with the appropriate error messages. 


When VARUPDE=NO is specified, the following occurs: 


e No validity checking is performed and no dialog variables are updated. 

¢ lf specified, the general exit is called. This assumes that the dialog command 
to be performed is one for which the exit program is normally called. 

e The specified function is performed unless the general exit program indicates 
that the UIM should not perform the function. For more information on exit pro- 
grams, see the System API Reference. 


When VARUPDE=NO is specified for a dialog command, which causes the UIM to 
return control to the application program, variable values entered by a user are not 
available to the application program. The values are stored for the panel and can 
be shown again by using the redisplay parameter of the Display Panel (QUIDSPP) 
API. For more information on this, see the System AP/ Reference. When 
VARUPDE=NO is specified on the CMD and CALL dialog commands, the UIM saves 
the screen copies of dialog variables and uses them when the panel is displayed 
again after the specified action completes. 


Note that when VARUPD=NO is specified on the CMD and CALL dialog com- 
mands, any modification of dialog variables or list entries causes the saved version 
to be lost. The saved version for any field is used if the underlying dialog variable 
has not changed since the field was saved. For lists, the saved version of a vari- 
able in a list entry is used unless one of the following occurs: 
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e Underlying list entry has changed 
e List entry changed position on the screen 
e List view has changed 


If a change was made, the saved version is lost and a new displayed value is 
derived from the dialog variable or list entry. 


For example, assume dialog variable VARX is present on panel PANELX and is 
modified by the user just before pressing a function key using the CALL dialog 
command where VARUPD=NO. If the target of that CALL dialog command modi- 
fied VARX, the saved version is lost. When the UIM displays the panel again after 
the call returns, the displayed version of VARX is based on the modification. This 
allows actions, which are unrelated to the current panel, to be performed without 
requiring the panel contents to pass all validity checks. VARUPD=NO should not 
be used with CMD or CALL dialog commands if the intended action is to use the 
same panel or any of its associated dialog variables, lists, or conditioning dialog 
variables. 


Panel Formatting Concepts 
When formatting UIM panels, keep the following in mind: 


e The application developer does not define the format of a panel in terms of 
rows and columns. Instead, the UIM interprets the descriptions of the tag lan- 
guage and then determines where to place each element in a panel. For 
example, the display panel (PANEL) tag contains a description of the panel 
title, but no explicit definition of where the title should be displayed. The UIM 
determines that the title should be centered within the panel width, intensified, 
and treated as mixed case. The same concept applies to all other areas of the 
panel, though most other examples are much more complex. 


e The UIM performs as much formatting as possible when the panel group is 
created, but the actual placement for many panel elements is determined at run 
time. This allows the UIM to consider screen depth and other run-time circum- 
stances. For example, the UIM allows menu items to be conditionally dis- 
played. These conditions are evaluated when a panel is displayed, and the 
format of the menu area is based on the results. 


When Panel Formatting Is Performed 
There is a difference between panel formatting and panel contents. Panel format- 
ting refers to the organization of the various areas on the panel. Panel contents 
refers to the values of fields as dictated by dialog variable contents. 


Panel formatting takes place when the panel group is compiled and again at run 
time. 


Most decisions are made when the panel group is compiled and the information is 
kept in the panel group object. Those formatting decisions that cannot be made 
when the panel group is compiled are made during Display Panel (QUIDSPP) API 
processing. 


An example of this distinction is a data item that is conditioned. All details about 


the prompt text layout, number of leader dots, field position, and formatting of pos- 
sible choices are performed when the panel is created. 
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At run time, the QUIDSPP API processing determines whether or not the item 
should be displayed by evaluating the conditions and builds an internal format. 
Within an application defined by the Open Display Application (QUIOPNDA) and 
Close Application (QUICLOA) APIs, each panel has only one internal format at any 
time. The internal format is built the first time the panel is displayed, and the 
format is kept for subsequent use until the application is closed. 


This does not mean that the internal format cannot change within an application. 
Most of the internal format does not change, but some panel elements such as 
menu items, list actions, and function keys, are conditioned by the application. The 
effect of changes to these areas are evaluated each time the panel is displayed, 
and then the format is updated. 


Because the UIM performs many functions, such as submitting commands and 
calling programs, before returning control to the application that called the 
QUIDSPP API, the specified panel can be presented to the user several times. 
Each time the panel is displayed, the UIM reevaluates the panel formatting. For 
example, pressing a function key causes an application program to be called. 
When the application program returns control to the UIM, the UIM displays the 
panel again, but only after checking to see if the application program changed the 
conditions that affected the internal format. For example, if the QUIDSPP API is 
called to display a panel with a menu area on it, and the application program 
changed a dialog variable affecting the conditioning of some of the menu items, 
when the UIM displays the menu area again, it reflects the changes. 


Application Control of Panel Formatting 


The language tags allows the application developer to control panel formatting in 
the following ways: 


e By specifying part of the formatting, such as column widths, vertical versus hori- 
zontal presentation of data areas, and depths of the areas. These specifica- 
tions are fixed when the panel is compiled and cannot be changed at run time 
by the application. This allows you to select alternate formatting techniques 
and it gives the UIM information that helps reduce run-time processing. 


¢ By specifying run-time conditioning. Dialog variables can be used to condition 
menu items, menu item groups, action list options, function keys, data items, 
pull-down choices, data selection fields, selection field choices, and data item 
groups. In most cases, these conditions are evaluated every time a panel is 
displayed to determine what should be included in the display. 


Conditioning can be based on any of the following: 
e Application defined dialog variable. 
e UIM defined dialog variable. 


e Existence of an object on the system or the user's authority to an object on the 
system. 


e User class of the application user. 


¢ Conditioning can be based on the setting of a user profile, a user class, or the 
Limit User Capability (ZLMTCPB) dialog variable. For more information on 
dialog variables, see “Dialog Variables Defined by UIM” on page A-166. 


For more information on defining conditions, see “COND (Condition Definition)” on 
page A-27. 
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The UIM allows additional control over conditioning. The panel definition can 
specify which conditions are evaluated only once, when first needed, or at all times. 
The purpose of this is primarily related to performance. Most items are conditioned 
on things that are or should be fixed when the panel is first displayed, such as a 
user profile and authorization. Specifying that these conditions be evaluated only 
once avoids unnecessarily evaluating the conditions. 


Limits of the Panel Formatter 


The UIM provides a formatter designed to handle most normal formatting require- 
ments. However, the formatter is not always able to match the results of manual 
formatting because the formatter is constrained by the run-time environment and 
also must handle generalized input. An example of this is formatting descriptions of 
function keys. Manual formatting might include changing the wording to achieve 
the best alignment and balance. The UIM does not have the option of changing 
the text length or assuming a balanced set of lengths. 


Generally, the closer information is packed on a panel, the less likely the UIM for- 
matter can match what manual formatting might achieve. 


Folding Up Multiple Panels When EXIT Is Requested 


To support the ability of an application to fold up multiple panels and programs as 
part of processing a single exit request, the operating system maintains a flag for 
each job indicating whether or not exit is requested. This exit flag is used in combi- 
nation with the user task parameter on the Display Panel (QUIDSPP) API to cause 
the exit request to fold up multiple panels. 


There are two ways the application program can turn on the exit flag: 


1. Specify the SET parameter on the EXIT dialog command. When the UIM per- 
forms the EXIT dialog command with the SET parameter, it turns on the job's 
exit flag. For more information on the EXIT dialog command, see Appendix B, 
“UIM Dialog Commands” on page B-1. 


2. Set the UIM-defined variable ZEXIT to "1" using the Put Dialog Variable 
(QUIPUTV) API. By setting this Z-variable, the UIM turns on the job's exit flag. 
The UIM automatically turns off the exit flag when it begins processing actions. 


Whenever the UIM regains control after performing a panel-defined action, such as 
submitting a command assigned to a function key or calling a program because a 
menu item is selected, the job's exit flag is checked. If the flag is on and the panel 
is displayed as an old user task (user task parameter on the QUIDSPP API), the 
UIM returns control to the calling application at that point. Also, the function- 
requested parameter of the QUIDSPP API contains an indication that the panel 
display ended due to the EXIT dialog command. 


If the job's exit flag is off or the panel is displayed as a new user task, nothing 
special happens. The UIM turns off the exit flag and displays the panel again. 


If the action performed is not panel-defined, for example, when a command is 


entered on the command line, the exit flag is always turned off, and the processing 
is not affected by whether the panel is displayed as a new or old user task. 
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An example of how the exit flag works follows; Figure 17-1 on page 17-25 illus- 
trates the example. Assume that program PGMX, displays PANELX that has a 
function key assigned to the CALL dialog command. Assume also that the program 
that is called, PGMY, displays another panel called PANELY. Now assume that 
PANELX is displayed as an old user task, the function key is pressed, and 
PANELY is displayed. From PANELY, the user presses the function key assigned 
to the EXIT dialog command using the SET parameter and control returns to 
PGMY. When the EXIT dialog command is processed, the UIM turns on the exit 
flag. If PGMY now returns control to the UIM, the UIM returns control to PGMX 
with an indication that the EXIT dialog command was requested. In effect, two 
panels are bypassed via a single exit request. 


>—> | 
PGMX 
QUIDSPP 
Job 
Exit 
Flag 
On 


PANELX (old user task) 


PGMY 
; 
EXIT QUIDSPP 
PANELY 


RV2W058-0 


Figure 17-1. Example of Job Exit Flag 

If the function key on PANELY assigned to the EXIT dialog command does not use 
the SET parameter, the UIM displays PANELX again because the job's exit flag is 
not turned on. 


For more information on APls, see the System API Reference. 
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Folding Up a List Panel 


For panels displayed as a result of processing a list option on an action list panel, 
the CANCEL, EXIT and ENTER dialog commands should work as follows. 


The operating system maintains a flag for each job indicating whether or not cancel 
is requested. This flag is similar to the flag described for exit processing; see 
“Folding Up Multiple Panels When EXIT Is Requested” on page 17-24. However, 
the cancel flag is not used to bypass more than one panel, and it is not used in 
conjunction with the user task parameter on the Display Panel (QUIDSPP) API. 


There are two ways the application program can turn on the cancel flag: 


1. Specify the SET parameter on the CANCEL dialog command. When the UIM 
performs the CANCEL dialog command with the SET parameter, it turns on the 
job's cancel flag. (For more information on the CANCEL dialog command with 
the set parameter, see Appendix B, “UIM Dialog Commands” on page B-1.) 


2. Set the UIM defined variable, ZCANCEL, to "1" using the QUIPUTV API. By 
setting this Z-variable, the UIM turns on the job's cancel flag. 


It is the application developer's responsibility to ensure that pressing the Cancel 
key stops processing of list actions and displays the action list panel again at the 
point where processing was stopped. If another panel can be displayed as a result 
of processing a list option, the job's cancel flag should be turned on when the 
Cancel key is pressed by specifying the SET parameter on the CANCEL dialog 
command. When the UIM performs action-list processing, it checks the cancel flag 
after each list action completes. When the UIM finds that the flag is on, it stops 
processing the remaining list options and displays the list again. The option field 
for the list entry just processed is cleared and the options of list entries whose 
action was not attempted are left in the list. The UIM only checks the cancel flag 
after processing a list action. 


It is the application developer's responsibility to ensure that pressing the Exit key 
stops the processing of list actions and either redisplays the action list panel at the 
point where processing was stopped or exits the action list panel. If another panel 
can be displayed as a result of processing a list option, the job's exit flag should be 
turned on when the Exit key is pressed by specifying the SET parameter on the 
EXIT dialog command. When the UIM performs action list processing, it checks the 
exit flag after each list action completes. When the UIM finds that the flag is on, it 
stops processing the remaining list options and the following occurs: 


e If the action list panel is displayed as a new user task, the panel is displayed 
again. 


e If the action list panel is displayed as an old user task, the panel is not dis- 
played again, and control is returned to the program that displayed the action 
list panel with a return function indicating EXIT was used. 


In either case, the option field for the list entry just processed is cleared and the 
options of list entries whose action was not attempted are left in the list. The UIM 
also checks the job's exit flag when it gets control back after processing menu 
options, function keys and pull-down menu choices. For more information, see 
“Folding Up Multiple Panels When EXIT Is Requested” on page 17-24 
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It is the application developer's responsibility to ensure that pressing the Enter key 
continues the processing of list actions. When neither the cancel flag nor the exit 
flag is on, the next list action is processed. 


Adding a Pop-Up Window over Another Panel 


You can add pop-up windows over another panel in one of the following ways: 


e Use the CALL dialog command to have the UIM call an application exit 
program so it can add and display the window. To achieve consistent results 
from the End Request (ENDRQS) command, this is the recommended design. 

e Use the RETURN dialog command to have the UIM return to the program that 
displayed the underlying panel so it can add and display the window. 


The UIM does not become a request processor program when displaying a panel in 
a pop-up window that has a menu or action list unless the panel also has a 
command line. This is true even when the window is displayed over a primary 
panel that has a command line, action list, or menu area. 


When the UIM becomes a request processor program while displaying a full-screen 
panel, and the application is designed to use the CALL dialog command to add and 
display a pop-up window, the program stack contains the UIM request processor 
program for the full-screen panel. However, when the application is designed to 
use the RETURN dialog command to add and display a window, the program stack 
does not contain the UIM request processor program. Therefore, the ENDRQS 
command causes different results depending on the internal design of the applica- 
tion. 


As a general guideline, you should avoid designing long-running functions that run 
as a result of a list option or menu option from a pop-up window, unless your 
program is a request processor at appropriate times. 


If your program becomes a request processor program and displays one or more 
pop-up windows by using a design that relies on the RETURN dialog command, 
then the code needs to clean up the window stack if the function that displayed a 
window is canceled by the ENDRQS command. When this happens, the Remove 
Pop-up Window (QUIRMVPW) API must be called once for each window to be 
removed from the application window stack. 


If your program becomes a request processor program and displays one or more 
pop-up windows by using a design that relies on the CALL dialog command, then 
the UIM cleans up the window stack automatically if the function that displayed a 
window is canceled by the ENDRQS command. 


For more information on a request processor program, see the CL Programming 
book. 


Using Menu Bars 


A menu bar is located at the top of a panel and extends the entire width of the 
panel. Menu bars are allowed only on panels that are 24 by 80 bytes or 27 by 132 
bytes and are not allowed within a pop-up window. 


The menu bar contains a list of choices that users may request. The choices are 
listed horizontally on one to three lines with three blanks between all choices. 
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When a user selects a choice by pressing the Enter key, a pull-down menu is dis- 
played directly below the menu bar. From this menu, the user may select one 
choice. 


Each choice in a pull-down menu does one of the following: 


e Performs an action against the panel or an area of the panel as a whole. In 
this case, the UIM performs the action once each time the choice is selected by 
the user. 


e Performs an action against each entry selected in an action list or selection list 
on the panel. In this case, the UIM performs the action once for each selected 
list entry. The user selects an entry or an action on a selection list by entering 
a slash (/) or country-designated selection character next to the desired entry. 


For more information on defining menu bars, see the following language tags in 
Appendix A, “UIM Panel Group Definition Language” on page A-1. 


e PANEL (Display Panel) 

e¢ MBAR (Menu Bar) 

¢ MBARC (Menu Bar Choice) 

¢ PDFLD (Pull-down Field) 

e PDFLDC (Pull-Down Field Choice) 


Differences Between Pull-Down Menus and Pop-Up Windows 


A pull-down menu visually appears similar to a pop-up window. While pull-down 
menus and pop-up windows overlay a portion of the underlying panel image, a 
pop-up window is a separate application panel and a pull-down menu is an exten- 
sion of the panel which contains the menu bar. 


Visually, a pull-down menu appears different from a pop-up window in the following 
ways: 


e The separator line appearing below the menu bar is always used as the top 
border of the pull-down menu. The border for a pop-up window is never part of 
the underlying panel. 


¢ A pull-down menu does not have a title. A pop-up window can have a title. 


¢ A pull-down menu does not have function key descriptions and a pull-down 
menu never overlays the function key descriptions of the underlying panel. 
Pop-up windows usually have function key descriptions and a window can 
overlay the function key descriptions of the underlying panel. 


e¢ A pull-down menu does not have a message line and any messages displayed 
as a result of the user interacting with the pull-down menu appear in the 
message line of the underlying panel. A pop-up window always contains a 
message line and any messages displayed as a result of interaction with the 
pop-up window appear in the message line of the pop-up window. 


Pull-down menus and pop-up windows also differ in how the user is allowed to 
interact with each. The differences are as follows: 


e When a pull-down menu is displayed, pressing the cursor tab key moves the 
cursor to the first unselected choice within the menu bar. Press the tab key 
again to move the cursor to the next unselected choice, until the cursor is 
moved back to the pull-down menu. When a pop-up window is displayed, 
pressing the cursor tab key moves the cursor to the next input field defined 
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within the pop-up window. The tab key never moves the cursor outside the 
border of the pop-up window. 


e When a pull-down menu is displayed, all the function keys defined for the 
underlying panel are active. Each function key performs the same function as 
if the pull-down menu was not displayed with the following exceptions: 


— The Enter key, or any other key assigned to the ENTER dialog command, 
is used to process the action assigned to the pull-down choice number 
selected by the user. 


— Any key assigned to the CANCEL dialog command causes the pull-down 
menu to be removed and the underlying panel to be redisplayed. Normally, 
F12 is the key assigned to the CANCEL dialog command. 


— The Page Down and Page Up keys, or any other key assigned to the 
PAGEDOWN or PAGEUP dialog commands, are not allowed when the 
cursor is within the pull-down menu. 


— Any key assigned to the PROMPT dialog command is not allowed when 
the cursor is within the pull-down menu. Normally, F4 is the key assigned 
to the PROMPT dialog command. 


For cursor-sensitive function keys, the user is allowed to move the cursor 
outside the border of the pull-down menu and press the function key. In this 
case, the UIM removes the pull-down menu and processes the action assigned 
to the function key as if the pull-down menu was not displayed at the time the 
user pressed the function key. Cursor-sensitive function keys are any keys 
assigned to the dialog commands in the following table. The dialog commands 
in the table are usually assigned to the keys as shown. 


Table 17-4. Cursor-Sensitive Function Keys Assigned to Dialog Commands 


Dialog Command That May Have a Dialog Command Is Usually Assigned to 
Cursor-Sensitive Function Key Assigned This Key 

HELP Help 

PAGEDOWN Page Down 

PAGEUP Page Up 

MOVETOP (move to top) F10 

CHGVIEW (change view) Fi 

PROMPT F4 


As an example, assume that a pull-down menu is displayed. If the user moves 
the cursor to a field in the underlying panel, outside the border of the pull-down 
menu, and presses the Help key, the UIM removes the pull-down menu and 
displays the contextual help defined for the field. 


When a pop-up window is displayed, only the function keys defined for the 
panel displayed within the window are active. When any function key is 
pressed and the cursor is located outside the border of the pop-up window, the 
window is redisplayed and the alarm sounds to indicate that the cursor is not 
allowed outside the window. 


Further differences between pull-down menus and pop-up windows are in how the 
application developer can control them. Following are the differences: 
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A pull-down menu can only contain a list of numbered choices. The application 
developer defines each choice, which appears in the pull-down menu, and also 
assigns an action for each choice. When the user selects one of the choices, 
the UIM performs the action defined for that choice. A pop-up window can 
contain any panel element, which can appear in a full-screen panel, with the 
following exceptions. 


— A pop-up window cannot contain a field (dialog variable) which spans mul- 
tiple lines of the display. Every field must fit within the width of the window. 
— A pop-up window cannot contain a menu bar. 


Based on user interaction, the UIM decides when a pull-down menu is dis- 
played and removed. The application program cannot control when a pull- 
down menu is displayed or removed; nor can the application program control 
the location or size of the pull-down menu when it is displayed. The application 
program has control over when and where a pop-up window is displayed and 
removed. For more information about displaying pop-up windows, see “Adding 
and Removing Windows” on page 17-31. The size of a pop-up window is 
specified by the application developer by specifying the WIDTH and DEPTH 
attributes on the PANEL tag for the panel to be displayed in the window. 


Using Pop-Up Windows 


A pop-up window is information that overlays part of the display. The user can 
view information inside the window and the portion of the screen that is not over- 
layed by the window. However, only the window is active; the user cannot work 
with the underlying panel. When more than one window is displayed, only one 
window is active at a time. 


Following are some principles of pop-up windows: 


Windows contain a message line, and if the message exceeds the boundary of 
the window, the message is truncated. To indicate the message is truncated, 
an ellipsis (...) is added to the end of the message. To see the rest of the 
message, place the cursor on the message line of the window and press the 
Help key. 


When a window is displayed, its size and location cannot be changed. 


The cursor is positioned in the active window. If the user moves the cursor 
outside the active window and presses any function key except Print, the 
display alarm sounds and the cursor moves back to its previous window 
location. 


When you leave a window, you are returned to the underlying display at the 
location where you were before you requested the window. 


The Print key applies to the entire display, not just to the current window. 


Defining Application Windows 
Application-defined windows can be displayed over UIM and DDS panels. 


Application-defined means that the application developer defines the exact size of 
the window on the display panel (PANEL) tag on the panel group source. The 
location of the window is specified when the application program calls the Add 
Pop-Up Window (QUIADDPW) API. 


17-30 Application Display Programming V4R1 


Adding and Removing Windows 
The UIM maintains a stack to keep track of windows. Windows can be added to 
the stack in one of the following ways: 


e The UIM adds windows to the stack in order to display help information and 
command line windows. 

e The application developer can request that a window be added to the stack to 
display a window. 


Windows can be removed from the stack internally by the UIM or by the application 
developer. 


Adding and removing windows is controlled by the application program, but the UIM 
provides a set of APIs to manipulate these windows. 


To display a window, an application program must first use the Add Pop-Up 
Window (QUIADDPW) API to inform the UIM that the next display is for a window. 
A window displaying a selection list should use field-adjacent positioning, while a 
window displaying a prompt for positioning a list should use offset positioning. 


The QUIADDPW API call does not specify the panel to be displayed in the window. 
It specifies only the location information necessary to position the window. 


A window can be added to a display only after a full-screen panel is determined. A 
full-screen panel is determined by calling the Display Panel (QUIDSPP) or Set 
Screen Image (QUISETSC) API. Once a full-screen panel is displayed within an 
application, a window can be added to the application. 


To position a selection list window using field-adjacent positioning, the programmer 
must specify the name of the field for which the selection window is being dis- 
played. When a panel is displayed within the window, the UIM uses a set of 
general window positioning rules to position the window so that, if possible, the 
window does not overlay the specified field. 


For a window displaying the prompt for positioning a list, offset positioning should 
be specified on the Add Pop-Up Window (QUIADDPW) API call. The upper left 
corner of the window is positioned below and indented to the right of the upper left 
corner of the underlying panel. 


Once a window is added to the display, the Display Panel (QUIDSPP) API is used 
to display a panel within the window. When the QUIDSPP API is called, the UIM 
performs the following operations: 


1. Determines the actual location for the window. The location is determined 
according to the location information provided by the call to the QUIADDPW 
API. 


2. Formats the panel. 


3. Merges the newly formatted panel and window border with the underlying panel 
image. 


4. Displays the merged panel output. 


The end user must interact with the most recently displayed window before inter- 
acting with any other underlying panel or window. 
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Use the Remove Pop-Up Window (QUIRMVPW) API to remove windows from the 
display. A window cannot be removed if the UIM is currently processing an action 
or running an exit program for the panel displayed in the window. Multiple windows 
can be removed at one time. 


The QUIRMVPW API does not cause the UIM to automatically display the under- 
lying panel again. The panel is displayed again without the window on the next call 
to the QUIDSPP API, or when the UIM automatically displays a panel again after 
processing a function or running an exit program. 


Using the Command Line in a Window 
A command line in a window allows the user to enter commands without requiring 
any reserved space on the panel for a permanent command line. The UIM pro- 
vides support to display a command line in a window. For UIM application panels, 
this is done by assigning a function key to the CMDLINE dialog command. The F9 
key is recommended. The CMDLINE dialog command is also allowed as the action 
for a choice in a pull-down menu. When a function key or pull-down field choice is 
assigned to the CMDLINE dialog command, the key or choice can be conditioned 
based on the ZLMTCPB dialog variable. Doing this only allows the user to get to 
the command line window if the user does not have limited capabilities. 


For DDS panels, a command line window can be provided by calling the 
QUSCMDLN API. 


Keep the following in mind when using a command line in a window: 


¢ A pop-up window is displayed when the user presses a function key causing 
the Command Line (CMDLINE) dialog command to process. The cursor is 
placed on the first position of the command line and the user can use the 
command line to enter any system commands. 


e The UIM provides a panel definition for the window and puts it at the bottom of 
the display. 


e Neither the size nor the location of the window for the command line can be 
changed. The user must remove the window by pressing the Enter key or the 
F12 (Cancel) function key. Running a command does not remove the window. 


The following example shows a command line pop-up window used on a display. 
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UIM as a Request Processor Program When Displaying a Panel 


Sometimes the UIM becomes a request processor program when displaying a 
panel. When the UIM becomes a request processor program, your application is 
isolated from commands entered on the command line. For example, if the End 
Request (ENDRQS) command is used to cancel a command entered on the 
command line, the UIM handles the end request and the application program is not 
ended. The following types of panels cause the UIM to automatically become a 
request processor: 


e Any panel with a command line. The UIM is required to be a request processor 
when submitting a command from a command line. When the panel has a 
command line, the UIM becomes a request processor program so that all func- 
tions it performs for the panel work consistently for the End Request (ENDRQS) 
command. 


e A full-screen panel with an action list. Most action list panels have a command 
line to allow parameters for list options. So for consistency, the UIM becomes 
a request processor program for all full-screen panels with an action list. This 
allows ACTOR=UIM action lists without a command line to work in the same 
way as those that have one when the ENDRQS command is requested while a 
list option is being processed. This allows a user to perform the ENDRQS 
command to cancel a long-running option without also canceling the action list 
panel and the program that displayed it. Any unprocessed list options are left 
pending in the action list when the ENDRQS command is used to cancel a 
UIM-processed list option. 


If you code ACTOR=CALLER for an action list, you should consider having 
your code become a request processor program for consistency with the UIM. 


e A full-screen panel with a menu area. Most menu panels have a command 
line. For consistency, the UIM becomes a request processor program for all 
panels with a menu area. This allows menu panels without a command line to 
work in the same way as those that have one when the ENDRQS command is 
requested while a menu option is being processed. This allows a user to 
perform the ENDRQS command to cancel a long-running option without also 
canceling the menu panel and the program that displayed it. 


If you code the RETURN dialog command for a menu item, you should con- 
sider having your code become a request processor program for consistency 
with the UIM. 


For more information on a request processor program, see the CL Program- 
ming book. 


Printing Concepts 


The UIM allows applications to define and generate printed output to the level 
required for the OUTPUT(*PRINT) parameter on a CL command. This support pro- 
vides a hardcopy form of information in a format similar to that displayed by the 
UIM, but it does not allow for generalized printing via the UIM. 


The application developer does not need to provide a print panel and a display 


panel. However, it is recommended that both print and display panels be placed in 
the same panel group. For printing panels, use the Print Panel (QUIPRTP) API. 
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A panel group can be opened for either display or print. Once a panel group has 
been opened for display, it can also be used to produce printed output. The Add 
Print Application (QUIADDPA) API is provided to open a printer file for an already 
open display application, and the Remove Print Application (QUIRMVPA) API 
closes the printer file that was opened with the QUIADDPA API. 


For more information on APls, see the System API Reference. 


The UIM tag language is used to define print head panels and print panels. The 
print head panel, created with the print head (PRTHEAD) tag, defines the header 
information that is printed at the top of each page. The print panel, created with 
the print panel (PRTPNL) tag, defines the different panel areas to be printed. Both 
the print head panels and print panels must be printed for the same open applica- 


tion. 


The following areas make up a printed listing and the example that follows is how it 


would look: 
Title 


Prolog 


Header 


Page body 


Trailer 


The title consists of two lines printed at the top of every page. The 
title lines contain information such as the output title, time and date, 
system name, product information, and page number. All of the infor- 
mation in the title lines is defined by the print head panel. 


(Optional.) The prolog section is printed only on the first page and 
comes right after the title lines. The prolog section is used for such 
things as indicating what parameters were specified to print the 
output. The prolog section is defined as the portion of the print head 
panel that has TYPE=PROLOG specified on the data presentation 
area (DATA) or information area (INFO) tag. 


(Optional.) The header section is used to print the same data on 
every page. This data usually includes things such as the file name, 
library, and member name for which information is printed. This 
section comes after the prolog on the first page and after the title 
lines on all remaining pages. The header section is defined as the 
portion of the print head panel that has TYPE=NORMAL specified or 
defaulted. 


The page body is made up of one or more panels of information. 
These panels of information appear very similar to panels that are 
used to display information on a display. These panels can contain 
data, information, and list areas. Menu areas and selection fields 
cannot be defined for printing. Because there is no such thing as a 
scrollable print panel, all information and data associated with the 
panel is printed via the Print Panel (QUIPRTP) API. 


The trailer is a single line of text that is printed after the last panel 
area on the last page. This trailer usually says something like 


END OF LISTING 
or 
END OF SOURCE 
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Page 1 Title time/date, system name 
Title product information, 


page number 


Prologue (optional) 
what parameters 
were specified 
Header (optional) 
file name, library, 
member name 


Page body 


(consists of one or more panels) 


data, information, list areas 


Page 2 Title same as page 1 


itle same as page 1 


a 


Header same as page 1 


Page body 


same as page 1 


Trailer (End of Listing) 


RV2W059-2 


Figure 17-2. Example of Printout 


Printing a Print Head Panel 


When a print head (PRTHEAD) panel is printed by calling the Print Panel 
(QUIPRTP) API, the heading is formatted and saved until a print panel is printed. 


Printing a Print Panel 


When a print panel (PRTPNL) is printed by calling the Print Panel (QUIPRTP) API, 
the UIM: 


1. Formats one page of data and prints it. 
2. Formats the next page of data and prints it. 
3. Formats page by page until the entire panel is printed. 


4. Formats and prints the last part of the panel on a partial page. The next call to 
the QUIPRTP API causes the rest of the partial page to be formatted and 
printed, assuming that no page eject is requested. If the first area of this next 
panel does not fit on one page, this area is printed on the next page. This 
causes the panel title, top separator, and area title, if one exists, to be printed 
on the next page. 
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Using Blank Lines for Separating 
A single blank line is inserted in the following places by the UIM: 


e After the second title line of every page 
e After list column and group headings 

e After data column headings 

¢ Before the trailer line 


Fonts and Highlighting 


Only printer files created without using a DDS source may be used by the UIM. No 
special fonts are supported. The H1 through H4 heading tags are printed as 
normal text with no highlighting or underlining. H1 headings are centered. 


The HPO through HP9 highlighting phrase tags are not allowed in print panel defi- 
nitions. Highlighting, underline, and double strike are not supported. (A double 
strike is when the printer prints a letter and then prints the same character or 
another character in the same position.) 


Printing the Trailer 


The one-line trailer is specified using the print trailer message (PRTTRAIL) tag ina 
print head panel. This is a one-line statement such as: 

‘END OF LISTING’. Itis printed at the end of an application's printout 
when the Remove Print Application (QUIRMVPA) or Close Application (QUICLOA) 

API is called. 


Defining Prolog Areas 


A print head panel (PRTHEAD) is used to define the prolog and header sections. 
The print head panel can contain only information and data areas. List areas are 
not allowed. 


With TYPE=PROLOG specified, the prolog section consists of one or more data 
areas, one or more information areas, or a combination of both. The prolog section 
is printed only from the first print head panel that is printed for each open printer 
file. An attempt to print a print head panel containing a prolog section causes an 
escape message if the print head panel is not the first one printed for an open 
printer file. 


Defining Header Areas 


With TYPE=NORMAL specified, the header section is made up of one or more data 
areas, one or more information areas, or a combination of both. The total depth of 

the information and data areas in the header section must be less than or equal to 

six lines. 


The minimum page length is 18 lines. To ensure that there is room for data on 
each page, with the possible exception of the first, the UIM limits the combined total 
depth of the prolog and header sections to 14 lines. If these maximums are not 
followed, a compile-time error message occurs. 


A title line must be printed at the top of every page, so the UIM requires that a print 
head panel be printed before any other print panels. The Print Panel (QUIPRTP) 
API needs to be called only once for the print head panel for each printer file. After 
that, the same header information is printed on each page of the printer file. To 
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change the header information, call the QUIPRTP API again for the same or dif- 
ferent print head panel. 


Using the Page-Eject Function During Printing 
An automatic page eject occurs when a print head panel is printed after printing a 
print panel. However, even if eject is specified on the print panel (PRTPNL) tag, 
when the next print panel is printed, it does not cause a second page eject. 


When a print head panel is processed by the Print Panel (QUIPRTP) API, it is not 
actually printed until another QUIPRTP API is called for a print panel. Therefore, if 
the QUIPRTP API is called for five different print head panels before the QUIPRTP 
API is called for a print panel, only the last print head panel affects the listing. 


Sharing and Overriding Printer Files 
The UIM allows multiple UIM applications to print to the same printer file by 
opening the printer file for sharing. However, the UIM does not share information 
between multiple UIM applications. 


If multiple UIM applications are printing to the same printer file, it is possible to 
have more than one prolog section per printer file, because a prolog section, if 
there is one, is printed once per open application. 


Care must be taken when working with a shared file to avoid inadvertently sharing 
with a higher or previous program in the program stack. Sharing a printer file 
between a UIM application and an application using a DDS record format file does 
not work. The shared file is closed when the last application sharing the shared file 
uses a Close Application (QUICLOA) or Remove Print Application (QUIRMVPA) 
API. 


The printer file is opened to allow most overrides. 


Printing Double-Byte Character Set (DBCS) Considerations 
The UIM checks the TXTMODE attribute of the panel group (PNLGRP) tag to deter- 
mine if double-byte data might be printed. If it might be printed, the UIM opens the 
printer file to contain DBCS data. For more information on DBCS, see Appendix D, 
“Double-Byte Character Set Support for Displays” on page D-1. 


Commonly Asked UIM Questions 
Here are some commonly asked questions which relate to exit programs and call 
programs: 


¢ What are exit programs and call programs? 


— Exit programs—uIM provides the ability for the user to define programs that 
are called after normal processing has completed in those cases where 
further processing on the data is required. For example, a general panel 
exit is allowed to do more specific validity checking on the panel than what 
UIM functions will handle. 

— Call programs—Call programs are programs that are written by the user to 
be called by UIM for such items as processing a function key, a pull-down 
option, or list option. This processing may include refreshing a list panel, 
calling another program to display a more detailed panel or to update a file 
with the information entered, and so on. 
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e¢ What is the difference between an exit program and a call program? 


— An exit program is called after normal processing is complete and a call 
program is called as part of the normal processing. Normal processing 


refers to processing items such as ACTION, ENTER, and PROMPT actions 
on a LISTACT tag. 
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Chapter 18. Making Online Help Information Accessible for 
Your Display File 


Application help is a function provided by the system that lets you define online 
help information for the records in a display file and then presents that help to the 
user when the Help key is pressed. 


The following illustration shows what happens when the Help key is pressed and 
online help information is available and accessible: 


User presses Help key 


| 
Display file suspended 


ay 1 


splay 
File 


Display 
la Y)- 


Online help information displayed 


Help XXX 


User exits help display 


fPY FFA or J 


Display file is displayed 


Display z 
File Display 
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Note: Caution is advised when using application help with multiple display stations 
acquired to the file because all display stations wait for the completion of 
the application help display. 


To provide online help information for your display, you need to do the following: 


e Add to your display file the necessary DDS keywords to make online help infor- 
mation accessible for your display. This chapter provides instructions for 
adding these keywords. 
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¢ Define the help information that the user sees using either a panel group, docu- 
ment, or record. Chapter 20, “Defining Online Help Information” on page 20-1 
provides instructions for defining the help information. 


;—— Information about DDS keywords 


For more information about the DDS keywords described in this chapter, see 
the DDS Reference. 


Enabling the Help Key 


If online help information is available for your display, you must enable the Help key 
on the keyboard. To enable the Help key, specify the HELP keyword at the file or 
record level of your DDS source. 


Choosing between Panel Groups, Documents, and Records for Help 


You can define online help information by using one of the following: 


Table 18-1. Different Ways to Define Online Help Information 


Method Description 

Panel group Objects into which user interface manager (UIM) source is entered 
Documents Objects created using AS/400 OfficeVision 

Records A set of DDS keywords contained in a source file member 


Each method has characteristics that can help you choose the method that will 
work best for you. The following table lists these characteristics and the method or 
methods that they apply to: 


Table 18-2 (Page 1 of 2). Characteristics of Different Methods of Online Help Information 


Panel 
Characteristic Groups Documents Records 
Accessible through H specifications for X X X 
DDS-described displays 
Allows cursor-sensitive help Xx xX xX 
Allows extended help Xx Xx xX 
Index search function available X 
InfoSeeker function available X 
Windows used X 
Hypertext linking available X 
Used by system displays xX 
Can be used for command help Xx 
Word processing functions, such as spell X (See xX 
checking, available note.) 
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Table 18-2 (Page 2 of 2). Characteristics of Different Methods of Online Help Information 


Panel 


Characteristic Groups Documents Records 


Bookmark and exit function available (allows X 
you to return to the same location in the help 
the next time you press the Help key) 


Allows printing of help information X X X 


Index for displayed information available X 


Table of contents for displayed information Xx 
available 


Can be placed in same member as display Xx 


source 


Same source type as display source X 


QUSRTOOL example available 


Option indicators allowed 


Supports DBCS online help information 


Right-to-left and left-to-right orientation of 
text 


<x |x| «| xX 


Supported for acquired devices X 


Defining Which Areas of Your Display Need Online Help Information 


You can define the display file so that you supply the online help information for all 
or part of a display, as represented by the shaded areas in the following figure: 
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Contextual help 

Information for rectangular areas that are defined by a record or part of a 
record format. Contextual information describes one or more fields on a 
display. 


Extended help 

All information for the entire display, beginning with the information about the 
purpose and use of the display and followed by contextual help for each field. 
Extended help is displayed when you press the Help key on an area of the 
display that does not have contextual help defined for it. If your online help 
information is defined using panel groups, you can also reach extended help 
from contextual help by pressing F2. 


The cursor location is determined when the Help key is pressed. If the Help key is 
enabled and the cursor is in any active help area, the online help information asso- 
ciated with that help area is displayed. 
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Each help area on a display is defined in the DDS source using the following: 


H specification 
Defines help for the containing record. An H in column 17 of the DDS 
source indicates a help specification level. The help specifications are 
defined before the first field in the record. 


Help Area (HLPARA) keyword 
Defines a help area by giving the upper-left row column and lower-right 
row column of the rectangular area. These coordinates must be located in 
the screen area, but are not required to be in the record area. 


If *RCD is specified for the HLPARA keyword, the help is associated with 
the entire record area, which includes all columns in the lines occupied by 
the record. When the cursor is located in the record area and the Help 
key is pressed, the online help information from the record on the HLPRCD 
keyword is displayed. 


Help (HLPxxx) keyword 
Defines whether a panel group (HLPPNLGRP), document (HLPDOC), or 
record format (HLPRCD) contains the actual online help information that 
you see when you press the Help key. 


The following illustration shows how H specifications are entered in your DDS 
source: 


wate Five bie aietave Pivle. bei Shel orach aieto-w a wvolase ch ate oa Aire ka ore aD elerece Pied Ss Otte Hancie od ance 
H HLPARA(*RCD) 
HLPxxx(required-variables) 


Figure 18-1. Sample H Specification in DDS Source 


This sample DDS defines help for a record. The required variables for the help 
keyword depend on whether HLPxx is defined as a HLPPNLGRP, HLPDOC, or 
HLPRCD keyword. Only one help keyword can be defined for the file, but you can 
specify one or more H specifications for a record. 


The order of H specifications is important because the first match found is selected. 
Therefore, the more specific HLPARA locations should be listed first. 


The following sample display is defined with two record formats, HEADER and 
SINFO: 
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1 

2 

3: 

4 

7 Add, Update, Display Supplier Record 

: HEADER 
7 Enter new or existing name: | (lines 5-7) 
ta] 

9 

10 

11 

12 

13 

14 

be Address: Record 
io ce ——__————— SINFO 
18 one _ (lines 15-17) 
19 

20 

21 

22 

2S 


ao a 
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The following table shows one way to define the online help information for the 
sample display: 


Table 18-3. Help for Sample Display 


Location on 

Display Location in DDS Source Description of Help Provided 

Lines 5-7 Entire record format HEADER Help is specified for the whole 

record 

Line 15 First line in record format SINFO Help is specified for the line only 

Line 16 Second line in record format Help is specified for the line only 
SINFO 

Line 17 Third line in record format Help is specified for the line only 
SINFO 

Remaining lines Areas in display file that are not Help is specified for the whole file 


defined with record formats 


Depending on the help method you plan to use, continue with any of the following 
to define H specifications in your DDS source: 


Panel groups (UIM) 

“Specifying Panel Groups for Help in Your Display File” on page 18-6 
Documents (OfficeVision) 

“Specifying Documents in Your Display File” on page 18-9 
Records (DDS) 

“Specifying Records in Your Display File” on page 18-12 


To compare and contrast the different ways to create online help information, see 


“Choosing between Panel Groups, Documents, and Records for Help” on 
page 18-2. 
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Specifying Panel Groups for Help in Your Display File 


The HLPPNLGRP keyword in DDS identifies the panel group that contains online 
help information for a display. The HLPPNLGRP keyword may be specified in an H 
specification or at the file level. To use the HLPPNLGRP keyword, you need to 
know the name of the help module and the name of the panel group and library 
that contains that help module. 


Several other DDS functions are available for use with panel groups. The functions 
and their associated DDS keywords are described in the following table: 


Table 18-4 (Page 1 of 2). Other DDS Keywords for UIM Help 


Function 


DDS keyword 


Description 


Defining the name of the 
help screen 


HLPTITLE 


The text to be displayed on the first line of 
the help display is defined with the file- or 
record-level DDS keyword HLPTITLE (Help 
Title). This text should be the name of the 
display that is displayed when the Help key 
is pressed. The HLPTITLE keyword must 
be used in the display file. This keyword is 
used only on full-screen displays of help 
when no help title is specified in the help 
source. 


Indicating full-screen 
online help information 


HLPFULL 


Using the DDS file-level HLPFULL (Help 
Full) keyword, the UIM-defined online help 
information for the application is displayed 
in a full-screen replacement display rather 
than in a window. 


When the HLPFULL keyword is not speci- 
fied, the help is displayed in a window 
unless the user's profile specifies other- 
wise. 


Excluding panel group 
help as secondary help 
information 


Enabling the Index 
Search function 


HLPEXCLD 


HLPSCHIDX 


The HLPEXCLD keyword excludes a help 
panel group with a duplicate name from 
being displayed within extended help. To 
do this, place HLPEXCLD on all but the 
first H specification that names an identical 
help panel group. HLPEXCLD indicates 
that the information associated with the H 
specification is not displayed as part of the 
extended help. 


When the HLPEXCLD keyword is not 
specified, extended help consists of the 
information associated with both the file- 
level HLPPNLGRP keyword (if any) and 
the HLPPNLGRP keywords on all active H 
specifications. 


At least one help panel group name must 
not specify the HLPEXCLD keyword. 


The Index Search function is enabled, and 
the search index object used for the Index 
Search function is specified by the file-level 
DDS keyword HLPSCHIDX (Help Search 
Index). 
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Table 18-4 (Page 2 of 2). Other DDS Keywords for UIM Help 


Function DDS keyword Description 
Enabling the InfoSeeker HLPSHELF The InfoSeeker function is enabled, and 
function the bookshelf used for the InfoSeeker func- 


tion is specified by the file-level DDS 
keyword HLPSHELF (Help InfoSeeker). 


Using the sample display from “Defining Which Areas of Your Display Need Online 
Help Information” on page 18-3, the following online help information is defined for 
each help area: 


( » 


1 

2 

3 

4 

: Add, Update, Display Supplier } Gea 
7 | Enter new or existing name: (lines 5-7) 
8 

9 

10 

a 

12 

13 

14 

: : Record 
16 pduress: SNES 

17 |City: ——EE———— i i 1eag 
18 |State: as (lines 15-17) 
19 

20 

0 

22 

23 

24 


X d 
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Table 18-5. Help for Sample Display Using Panel Groups 


Name of Help Module in Panel 

Location on Group SMPPNL in Library 
Display Location in DDS Source SMPLIB 
Lines 5-7 Entire record format HEADER HLPCMPY 
Line 15 First line in record format SINFO HLPADDR 
Line 16 Second line in record format HLPCITY 

SINFO 
Line 17 Third line in record format HLPST 

SINFO 
All shaded Areas in display file that are not SUPHELP 
areas defined with records 


The following DDS source shows how the help areas are defined for the sample 
display using panel groups: 
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ioe biti ls eb sec lorew teed ts tees Asean Dewees oe Oc oben h ce 


R HEADER 
H 


CONAME 
R SINFO 
H 
H 


H 


ADDR 


CITY 


STATE 


10A 


30A 


10A 


2A 


NNO 


HELP 

HLPPNLGRP(SUPHELP SMPLIB/SMPPNL) 

HLPTITLE('ADD,UPDATE,DISPLAY SUPPLIER') 

OVERLAY 

HLPARA(*RCD) 

HLPPNLGRP(HLPCMPY SMPLIB/SMPPNL) 
25'ADD, UPDATE, DISPLAY SUPPLIER’ 
10'ENTER NEW OR EXISTING NAME: ' 

47 

OVERLAY PROTECT 

HLPARA(15 1 15 79) 

HLPPNLGRP(HLPADDR SMPLIB/SMPPNL) 

HLPARA(16 1 16 79) 

HLPPNLGRP(HLPCITY SMPLIB/SMPPNL) 

HLPARA(17 1 17 79) 

HLPPNLGRP(HLPST SMPLIB/SMPPNL) 
10'ADDRESS: ' 

32 
10'CITY:' 
32 
10'STATE:' 
32 


Figure 18-2. Sample DDS Source Showing HLPPNLGRP 


The file-level help in SUPHELP provides extended help for the display (when the 
cursor is not located in the record area for either HEADER or SINFO) because 
HLPARA(*RCD) is the location specified on the H specification. 


The panel groups that contain the online help information must be created by using 
the UIM source from a source file member. More information about creating panel 
groups is found in “Defining Online Help Information in a Panel Group” on 


page 20-1. 


Note: HLPPNLGRP and HLPRCD are not allowed in the same display file; 
HLPPNLGRP and HLPDOC are also not allowed in the same display file. 


Defining Panel Groups with Option Indicators: The HLPPNLGRP keyword can 
be specified with option indicators. In the following example, assume the SINFO 
record has indicator 90 on and the cursor is in the help area defined for the H 
specification. When the Help key is pressed, the panel group HELP1 is displayed. 
If indicator 90 is off, panel group HELP2 is displayed. 


The DDS for this file is: 
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R HEADER OVERLAY 
5 25'ADD, UPDATE, DISPLAY SUPPLIER' 
7 10'ENTER NEW OR EXISTING NAME' 


CONAME 10A I 7 47 
R SINFO OVERLAY PROTECT 
H HLPARA(15 9 15 61) 
90 HLPPNLGRP(HELP1 SMPLIB/SMPPNL) 
H HLPARA(15 9 15 61) 
N90 HLPPNLGRP(HELP2 SMPLIB/SMPPNL) 
15 10'ADDRESS' 
ADDR 30A B15 32 


Figure 18-3. Sample DDS Source Showing HLPPNLGRP and Option Indicators 


Copying QUSRTOOL Examples That Specify Help Using Panel Groups 
The QUSRTOOL library provides four sample DDS-described displays that access 
online help information using panel groups. You can copy the source for these 
sample displays into a library of your choosing and then tailor them for your own 
use. For more information about these sample displays, see “Using the Displays 
Example in the QUSRTOOL Library” on page 21-1. 


Specifying Documents in Your Display File 


Online documents used as help information are created by using the word pro- 
cessing function of the OfficeVision licensed program. The document and folders 
do not have to exist when you create the display file. More information about cre- 
ating documents for help is found in “Defining Online Information in a Document” on 
page 20-18. 


The source of the online help information that is identified by a help document in 
DDS source is specified with the help-specification or file-level DDS keyword 
HLPDOC (Help Document). To use the HLPDOC keyword, you need to know the 
names of the document and folder (or folders) where the information is stored and 
the help information label name that marks the specified location in the document 
where the information is located. 


Using the sample display from “Defining Which Areas of Your Display Need Online 


Help Information” on page 18-3, the following online help information is defined for 
each help area: 
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p Y 


1 

2 

a 

4 

eS Add, Update, Display Supplier | ek 
7 Enter new or existing name: (lines 5-7) 
8 

10 

11 

12 

3 

44 

15 

16 |Address: ceo 
17 (City: ————__—— 
18 |State: (lines 15-17) 
19 

20 
3 

22 

25 

24 qq ” 
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Table 18-6. Help for Sample Display Using HLPDOC 


Name of Help Infor- 


Location on mation Label (See 
Display Location in DDS Source Note.) 

Lines 5-7 Entire record format HEADER HLPCMPY 

Line 15 First line in record format SINFO HLPADDR 

Line 16 Second line in record format SINFO HLPCITY 

Line 17 Third line in record format SINFO HLPST 

All shaded areas Areas in display file that are not defined SUPHELP 


with records 


Note: All help information labels are contained in sample document HELP.DOC in sample 
folder HELPFLD. 


The following DDS source shows how the help areas are defined for the sample 
display using help documents: 
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sejathierens oaks sree PoreesOeteciet oct d ac nat emen A set cee De tees hues Ot ce Pcie wae 


HELP 

HLPDOC(SUPHELP HELP.DOC HELPFLD) 
R HEADER OVERLAY 
H HLPARA(*RCD) 


HLPDOC(HLPCMPY HELP.DOC HELPFLD) 


5 25'ADD, UPDATE, DISPLAY SUPPLIER' 
7 10'ENTER NEW OR EXISTING NAME: ' 
CONAME 10A I 7 47 
R SINFO OVERLAY PROTECT 
H HLPARA(15 1 15 61) 
HLPDOC(HLPADDR HELP.DOC HELPFLD) 
H HLPARA(16 1 16 41) 
HLPDOC(HLPCITY HELP.DOC HELPFLD) 
H HLPARA(17 1 17 33) 


HLPDOC(HLPST HELP.DOC HELPFLD) 
15 10'ADDRESS: ' 


ADDR 30A B15 32 

16 10'CITY:' 
CITY 10A B 16 32 

17 10'STATE:' 
STATE 2A B17 32 


Figure 18-4. Sample DDS Source Showing HLPDOC 


The file-level help in SUPHELP is used to provide extended help for the display 
(when the cursor is not located in the record area for either HEADER or SINFO) 
because HLPARA(*RCD) is the location specified on the H specification. 


The DDS keywords HLPDOC and HLPPNLGRP are not allowed in the same 
display file. The keywords HLPDOC and HLPRCD are allowed in the same display 
file; however, several considerations apply when mixing the two keywords. For 
more information about HLPRCD and these considerations, see “Specifying 
Records in Your Display File” on page 18-12. 


Defining Documents with Option Indicators: The HLPDOC keyword can be 
specified with option indicators. In the following example, assume the SINFO 
record is put with indicator 90 on and the cursor is in the help area defined for the 
H specification. When the Help key is pressed, the HELP#1 document in folder 
HELP.F1, starting at location CITY1, is displayed. If indicator 90 is off, the HELP#2 
document in folder HELP.F1, starting at location CITY2, is displayed. 


The DDS for this file is: 
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OVERLAY 


5 25'ADD, UPDATE, DISPLAY SUPPLIER' 
7 10'ENTER NEW OR EXISTING NAME' 


R HEADER 
CONAME 10A I 7 47 
R SINFO 
H 
90 
H 
N90 
15 10 
ADDR 30A B15 32 


OVERLAY PROTECT 
HLPARA(15 9 15 61) 


HLPDOC(CITY1 HELP#1 HELP.F1) 


HLPARA(15 9 15 61) 


HLPDOC(CITY2 HELP#2 HELP.F1) 


‘ADDRESS ' 


Figure 18-5. Sample DDS Source Showing HLPDOC and Option Indicators 


Specifying Records in Your Display File 


The source of the online help information that is identified by a help record in DDS 
source is specified with the help-specification or file-level DDS keyword HLPRCD 


(Help Record). 


HLPRCD and HLPPNLGRP are not allowed in the same display file. 


Using the sample display from “Defining Which Areas of Your Display Need Online 
Help Information” on page 18-3, the following online help information is defined for 


each help area: 


a 


SB OO MNAUNAWN . 


16 |Address: 


Add, Update, Display Supplier 


Enter new or existing name: 


> 


17° (City: 


18 |State: 


_ 


d 
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Record 
HEADER 
(lines 5-7) 


Record 
SINFO 
(lines 15-17) 


Table 18-7. Help for Sample Display Using HLPRCD 


Location on Name of Record Format that 
Display Location in DDS Source Contains Help 
Lines 5-7 Entire record format HEADER Record format HLPCMPY 
Line 15 First line in record format SINFO Record format HLPADDR 
Line 16 Second line in record format Record format HLPCITY 
SINFO 
Line 17 Third line in record format Record format HLPST 
SINFO 
All shaded Areas in display file that are not Record format SUPHELP 
areas defined with help record 


The following DDS source shows how the help areas are defined for the sample 
display using help records: 


HLPRCD(SUPHELP) 
R HEADER OVERLAY 
H HLPARA(*RCD) 
HLPRCD(HLPCMPY) 
25'ADD, UPDATE, DISPLAY SUPPLIER’ 
10'ENTER NEW OR EXISTING NAME: ' 
47 


N™N Oo 


CONAME 10A I 


R SINFO 
H 


H 


H 


OVERLAY PROTECT 
HLPARA(15 1 15 61) 
HLPRCD(HLPADDR) 
HLPARA(16 1 16 41) 
HLPRCD(HLPCITY) 
HLPARA(17 1 17 33) 


HLPRCD(HLPST) 
15 10'ADDRESS: ' 
ADDR 30A B15 32 
16 10'CITY:' 
CITY 10A_ B 16 32 
17 10'STATE:' 
STATE 2A B17 32 


Figure 18-6. Sample DDS Source Showing HLPRCD 


The file level help is used to provide general help for the display when the cursor is 
not located in any of the defined help areas for either HEADER or SINFO. 


You are not required to define each help area with a different record. This means 
that the same record may be used to define one or more help areas on a display, 
including the help area that defines the entire display. 


Defining Records with Option Indicators: Tne HLPRCD keyword can be speci- 
fied with option indicators. In the following example, assume the SINFO record is 
put with indicator 90 on and the cursor is in the help area defined for the H specifi- 
cation. When the Help key is pressed, the record HELP#1 is displayed. If indicator 
90 is off, the record HELP#2 is displayed. 
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The DDS for this file is: 


R HEADER 
CONAME 
R SINFO 
H 
90 
H 
N90 
ADDR 


OVERLAY 
5 25'ADD, UPDATE, DISPLAY SUPPLIER’ 
7 10'ENTER NEW OR EXISTING NAME' 
10A I 7 47 
OVERLAY PROTECT 
HLPARA(15 9 15 61) 
HLPRCD(HELP#1) 
HLPARA(15 9 15 61) 
HLPRCD(HELP#2) 
15 10'ADDRESS' 
30A B15 32 


Figure 18-7. Sample DDS Source Showing HLPRCD and Option Indicators 


Entering the Records That Contain the Help Information 


The records that give the actual online help information may be included in the 
same file as the DDS source for the application display. The records may also be 
contained in a different file. If the records are contained in a different file, the file 
and the library that contains the file must be identified on the HLPRCD keyword. 


Regardless of where the information is contained, the DDS source for the previous 


example looks like the following: 


l pasties lea Sathyeneeeveaies oa deeatenss 4s oars S ae hvsaw bene d teete bene 


R SUPHELP 


R HLPCMPY 


R HLPADDR 


R HLPCITY 


R HLPST 


2 5'TO ADD, UPDATE, OR DISPLAY - 
THE SUPPLIER NAME AND - 
ADDRESS, ENTER THE SUPPLIER - 
NAME. ITS CURRENT ADDRESS, - 
IF ANY, WILL BE SHOWN AND MAY - 
BE UPDATED. ' 


2 5'ENTER THE FIRST 10 - 
CHARACTERS OF THE COMPANY ' 


2 5'ENTER THE NEW OR CHANGED - 
ADDRESS. ' 


2 5'ENTER THE FIRST 10 - 
CHARACTERS OF THE CITY' 


2 5'ENTER THE 2 CHARACTER ABBR - 
FOR THE STATE. ' 


Figure 18-8. Sample DDS Source with HLPRCD 
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Using Records and Documents for Help in the Same Display File 
HLPRCD and HLPDOC are allowed in the same display file; however, the following 
considerations apply: 


When the Help key is pressed with the cursor location in a help area described 
by a document, that document is the only help displayed when the roll keys are 
used. No other document or help records are displayed. 

When the Help key is pressed with the cursor location in a help area described 
by a record, the normal sequencing used for records is followed with docu- 
ments being ignored. 

The HLPDOC and HLPRCD keywords cannot both be specified at the file level 
or on the same H specification. 

The HLPBDY keyword cannot be specified with the HLPDOC keyword. For 
more information about the HLPBDY keyword, see “Displaying Secondary 
Online Help Information” on page 18-17. 


Understanding the Restrictions on Records 
The following restrictions apply when using the record form of application help: 


The application program does not control the displaying of the records. When 
the Help key is pressed, the system controls the displaying of help. Because 
the system does not control the buffers or hidden message line areas of the 
application program, the following takes place: 


— Output fields in the record formats are displayed as blanks. 
— The ALIAS keyword is allowed but ignored. 


— CSRLOC and MSGID are processed by the system, but the hidden and 
program-to-system fields are not passed from the application program. 


No input is returned to the user program: 


— Input-capable fields on a record are displayed with underlines; however, no 
input is returned to the application program. Any input typed in an input 
field is lost when application help is finished. 


— Response indicators are not returned. 
Help records can contain H specifications, but they are ignored. 
Option indicators are assumed to be off. 
Screen size conditioning can be used. 
Only the following keywords are active when specified for records: 


COLOR 

DATE 

DFT 

DSPATR 

DSPSIZ 

MSGCON 
MSGLOC 

TEXT 

SLNO (constant value). If SLNO(*VAR) is specified, 1 is used for the 
starting line number. 
SYSNAME 

TIME 

USER 
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All other display file keywords, though allowed, do not make sense for records 
and may or may not be processed while displaying the help. 


Paging between Help Displays That Use Records 
If you use records to define help information, the first display that appears when the 
Help key is pressed is called primary help. When a Roll Up or Roll Down key is 
pressed on a primary help display, secondary help is shown. 


Understanding How the System Pages Help Displays 

The system maintains a list of all active H specifications from record formats that 
are on the display. This list of H specifications is called the help list. The H spec- 
ifications on the front of the help list are the first to be searched when the user 
presses the Help key. 


Pressing the Help key in a help area on the display does the following: 


Display - 
File Display Help XXX 
Py (ZO) 
H : 
H ao ‘ 


U 


ae 


1 | 2 EI 4 
RV2W019-3 

Suspends the display file. 

Searches the list of active help areas to find the first one in the list that con- 
tains the cursor location when the Help key is pressed. 

Opens the display file that contains the help record and displays the informa- 
tion. 

EJ Allows the user to roll forward or backward through the online help informa- 
tion. 


The order and content of the H specifications in the list are determined by the fol- 
lowing: 
e When a record format is added to the display, the H specifications for that 
record format are placed on the front of the list. 


e lf the record format contains more than one H specification, they are added to 
the help list in the order in which they are defined in the display file. 


¢ The help list is cleared either when a record format is written that clears the 
display, or when one is written that has the HLPCLR keyword enabled. 


e If arecord has the OVERLAY keyword in effect, has H specifications, or com- 
pletely or partially overlaps another record already on the display, the help list 
is updated in different ways. The following table describes the type of help-list 
updating for records for each combination of the three factors: 
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Overlay H Specifications Overlaps Help List Update 


No No N/A Help list is cleared. 

No Yes N/A Help list is cleared and H specifica- 
tions for the record are added to the 
help list. 

Yes No No Help list is not changed. 

Yes No Yes H specifications are removed from 


the help list if they are within the 
boundaries of the record being 
written. 

Yes Yes No H specifications for the record are 
added to the help list. H specifica- 
tions are removed from the help list if 
they are within the boundaries of any 
H specification in the record being 
added. 

Yes Yes Yes H specifications are removed from 
the help list if they are within the 
boundaries of the record being 
written. Then the H specifications for 
the record are added to the list. 
Finally, H specifications are removed 
from the help list if they are within 
the boundaries of any H specification 
in the record being added. 


Note: An H specification with “NONE specified for the help area is removed from 
the help list when the first H specification with a help area defined above it 
is removed. If a help specification with “NONE specified for its help area is 
the first help specification, then it is only removed when the help list is 
cleared or when a help specification with a help area is placed above this 
help specification. This H specification is removed when the one above it is 
removed. 


Displaying Secondary Online Help Information 

The record formats that are displayed as secondary help come from the same help 
group, or if none is available there, from the same help sublist as the record format 
that is currently displayed. 


A help group is defined with the HLPSEQ keyword and consists of those record 
formats that have the same group name specified. The HLPSEQ keyword allows 
you to specify the help group name and the help sequencing number. The help 
sequencing number specifies the order in which the help will be displayed. If two 
record formats that are in different display files happen to have the same group 
name, they are still considered to be in separate help groups. Record formats that 
do not have a HLPSEQ keyword specified are considered to be groups of one. 


A help sublist contains all of those H specifications defined between help bounda- 
ries. The HLPBDY keyword partitions the help list into sublists by defining help 
boundaries. (The H specification that has the HLPBDY keyword coded is consid- 
ered to be before the boundary.) Sublists are important when using the roll keys to 
look at more online help information. 
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Determining the Sequence of Secondary Help: Depending on whether you are 
using the Roll Up or Roll Down key, the system selects secondary help as follows: 


1. A help record format that is in the same help group as the current help record 
format and has the next highest help sequencing number (if the Roll Up key is 
pressed) or next /Jowest help sequencing number (if the Roll Down key is 
pressed) is selected. 


2. If the current help record format already has the highest help sequencing 
number (if the Roll Up key is pressed) or the /owest help sequencing number (if 
the Roll Down key is pressed) in the group, the help sublist is searched for the 
next H specification that does not refer to the same help group as the currently 
displayed record format. 


Notes: 


a. To prevent including unexpected help, it is recommended that the HLPBDY 
keyword be specified on the last H specification in each record of the appli- 
cation display file. This defines one sublist for each record that has help. 
However, if multiple records are on the screen, this may not be desirable. 
In this case, the HLPBDY keyword should be in effect only on the last 
record put to the screen. 

b. Because this second method works only when a sublist can be identified, it 
is not used if the primary help was the default record format for the file (for 
example, if it was selected from the file-level HLPRCD keyword). 


3. Searching in the sublist continues until the boundary of the sublist is reached. 
The search then wraps to the other end of the sublist and continues until the 
current H specification being displayed is reached. 


4. If no H specification that has a satisfactory HLPRCD is found, the record format 
in the help display file that has the same help group name and the /owest help 
sequence number (if the Roll Up key is pressed) or the highest help sequence 
number (if the Roll Down key is pressed) is selected. This method always finds 
a match because the current help format always meets this criteria if no other 
format does. 


In the following example, the fields and HLPARA keywords are not specified 
because neither has an effect on the order of secondary information: 


HELP 
HLPRCD(HELP11) 

R RECORD1 

H HLPRCD(HELP1) 

H HLPRCD(HELPSCR1) 
HLPBDY 

H HLPRCD(HELP2SRC) 
HLPBDY 


Figure 18-9. Sample DDS Source to Show Secondary Help 


The sample file HELPFILE contains the following record formats with HLPSEQ 
keywords coded as shown: 


18-18 Application Display Programming V4R1 


Record Keyword Specification 


HELP HLPSEQ(GROUPA 1) 
HELP4 HLPSEQ(GROUPA 2) 
HELP11 HLPSEQ(GROUPA 3) 
HELPSCR1 HLPSEQ(GROUPB 1) 
HELPSCR2 HLPSEQ(GROUPB 2) 
HELP2SRC 


Note that the help record formats HELP and HELPSCR2 are not referred to in the 
application display file. Because they are not referred to in this way, they are not 
primary help, but they are displayed as secondary help as follows: 


Sequence 1: 
Primary help format HELP11 
Press Roll Down HELP1 
Press Roll Down HELP 
Press Roll Down HELP11 


In this first sequence, HELP1 is shown when the Roll Down key is pressed 
because this is the previous help record format in GROUPA. Similarly, HELP is 
shown when Roll Down is pressed the second time. When Roll Down is pressed 
the third time, the end of the help group is reached. HELP11 is then selected 
again because it is the last help record format in the original help group. 


Sequence 2: 
Primary help format HELPSCR1 
Press Roll Up HELPSCR2 
Press Roll Up HELP1 
Press Roll Down HELP 


The second sequence starts with HELPSCR1 being displayed as the primary help 
record format. Pressing Roll Up causes HELPSCR2 to be displayed because it is 
the next help record format in GROUPB. Rolling up again runs off the end of the 
group and HELP1 is found because it is the next help record format found, after 
wrapping, in the sublist that contains HELPSCR1. Pressing Roll Down now causes 
HELP to be displayed because it is the previous entry in GROUPA. 


Sequence 3: 
Primary help format HELP2SRC 
Press Roll Up or Down HELP2SRC 


Because HELP2SRC is not in a help group and is the only one in its sublist, 
HELP2SRC is to be shown when rolling in either direction. 


Understanding the Restrictions of Records for Secondary Help: The following 
restrictions apply when using the record form of application help: 
e Application help controls all function keys when a help record is displayed: 


— The Roll Up key is enabled and causes the next record to be displayed 
according to the rules for displaying secondary help. 


— The Roll Down key is enabled and causes the previous record to be dis- 
played according to the rules for secondary help. 


— The Enter key is enabled and causes a return to the application program. 
Any CAnn or CFnn key enabled for the record will also cause a return to 
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the application program. All other function keys, including the Help key, are 
ignored. 


e Records with the USRDFN, SFL, and SFLCTL keywords may not be used as 
records. When a display file is created, a diagnostic is issued if the HLPSEQ 
keyword is found on a record with one of these keywords. When the applica- 
tion is running, error reset message CPD4050 is issued if a record with one of 
these keywords is used as help. The help record is not displayed. 


The KEEP and ASSUME keywords should be avoided on records because they 
cause results that cannot be predicted. 


Returning Control to Your Program after Pressing the Help Key 


Depending on how you code your DDS, you can return control to your program in 
one of two ways after you press the Help key: 


e You can display online help information and then return control to the program. 
e You can return control to the program immediately without displaying the online 
help information. 


Returning Control to Your Program after Showing the Help Display 
Use the help command key (HLPCMDKEY) keyword to return control to your appli- 
cation program from the application help record format after a command attention 
(CAnn) or command function (CFnn) key has been pressed. A CFnn key returns 
data to the application program, while a CAnn key does not return data to the appli- 
cation program. 


The command key must apply to both the application record format and the 
application-help record format. If a CAnn or CFnn key does not apply to the 
application-help record format, the HLPCMDKEY keyword is ignored. 


The following DDS source, which uses help records, shows how the HLPCMDKEY 
keyword is specified: 
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R APPRCD 


INPUT1 
INPUT2 
INPUT3 


R HELPRCD 


10 B 
10 B 
10 B 


HELP 
HLPRCD(HELPRCD) 
HLPARA(1 1 24 80) 
8 2'THIS IS THE APPLICATION’ 
9 2'RECORD FORMAT' 
12 10 
13 10 
14 20 


HLPCMDKEY 
CAO1 
CFO3 
8 2'SPECIFY COMPANY NAME' 
9 2'SPECIFY STREET' 
10 2'SPECIFY CITY, STATE, ZIP' 


Figure 18-10. Sample DDS Source to Show HLPCMDKEY 


If the user is on the application help display that uses the previous data description 
specifications, the following happens when the various keys are pressed: 


e¢ The CF04 key, which is specified only on the application record format, acts the 


same as the Enter key. 


e¢ The CMD3 key acts the same as the Enter key. Corresponding CAnn or CFnn 
keys must be specified on both the application-help record format and applica- 
tion record format for control to return to the program. 


e¢ The CA01 key returns control to the application program. 


In the next example, response indicators are used. When a response indicator is 
specified on a CAnn or CFnn key on the application record format (for example, 

CF12(12)), the response indicator is returned after the application-help record 
format is displayed. When a response indicator is specified on a CAnn or CFnn 
key on the application-help record format (for example, CF01(11)), the response 


indicator is ignored. 
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R APPRCD CAO1 
CA03 
CF12(12) 
HELP 
H HLPRCD(HELPRCD) 


HLPARA(1 1 24 80) 
8 2'THIS IS THE APPLICATION’ 
9 2'RECORD FORMAT' 


INPUT1 10 B 12 10 
INPUT2 10 B 13 10 
INPUT3 10 B 14 20 
* 
R HELPRCD HLPCMDKEY 
CFO1(11) 
CF12 


8 2'SPECIFY COMPANY NAME' 
9 2'SPECIFY STREET' 
10 2'SPECIFY CITY, STATE, ZIP' 


Figure 18-11. Sample DDS Source to Show HLPCMDKEY and Response Indicators 


Returning Control to Your Program without Showing the Help Display 


Use the HLPRTN keyword to immediately return control to your program (instead of 
displaying help) when the Help key is pressed. 
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Chapter 19. Making Online Help Accessible for Your Panel 
Group 


The Help key on most keyboards is either a key specifically labeled Help, or it is a 
key defined to work as a Help key and labeled with another name. This varies 
among keyboards, but the F1 key is commonly defined as an alternate for the Help 
key. 


When the user presses the Help key, a sequence of events occur, as illustrated by 


the following diagram: 


UIM Panel 


User presses Help key 


Flo 
| 


Online help information displayed Current UIM 
panel is 
displayed 

Help XXX 


User exits help display 


‘ 


1 
If the cursor is on a hypertext link when you press the 
Enter key, instead of returning to the current UIM panel, 
you are taken to the hypertext information. 


RV2W061-2 


When the user presses the Help key, the current panel is suspended by the UIM 
and a help panel is displayed with information about a specific item, group of items, 
area on a panel, or the entire panel. When the user has read the displayed help, 
the user presses the F3, F12, or Enter key to return to the current panel before the 
Help key was pressed. 


Definitions and Explanations 


Help for a panel is constructed from help modules referred to in the panel definition. 
The UIM requires you to define online help information for panels in a panel group, 
and presents the help to the user when the HELP dialog command is requested. 
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The user requests the HELP dialog command by pressing a key assigned to it. 
Typically, the engraved Help key and the F1 key are assigned to the HELP dialog 
command. In this section, the term Help key refers to any key which is assigned 
to the HELP dialog command. 


Online help information is the information displayed to the user when the Help 
key is pressed on the keyboard. The level of help displayed depends on the 
location of the cursor when the user presses the Help key. 


Help is always available for the entire panel. This help is known as extended 
help, which is the general information for a panel. Extended help begins with infor- 
mation about the purpose and use of the panel and is followed by contextual help 
for each item on the panel. Extended help includes contextual help for items that 
do not currently show on the screen, but which can be shown by using the Page 
Up and Page Down keys. (Contextual help provides information about a single 
item or group of related items where the cursor is positioned when the user 
requests help.) An item is excluded from extended help when the item is not cur- 
rently active for the panel by using the COND attribute for a specific item on the 
panel. 


Extended help is displayed when the Help key is pressed for an area of the screen 
that does not have contextual help defined. It is also displayed when the user 
presses F2 (Extended help) while viewing contextual help. 


The extended help is defined on the HELP attribute of the display panel (PANEL) 
tag. This attribute identifies the help module containing the beginning of the 
extended help for the panel. 


When coding online help for a panel, the tag which actually contains the information 
that is displayed when the user presses the Help key is the help module (HELP) 
tag. For more information on the attributes of this tag, see “HELP (Help Module)” 
on page A-60. 


To code for help in a panel, the HELP attribute must be specified on the tag for 
which the help is provided. The name of the help module containing the help infor- 
mation is specified on the HELP attribute of a tag. 


The help module identified on a HELP attribute exists in the same panel group or 
menu where that HELP attribute appears, or in another panel group. When the 
panel group or menu is created, the UIM compiler determines the panel group in 
which the UIM will find the help module when the Help key is pressed by finding a 
help module name that matches the name specified on the HELP attribute in one of 
the following places: 


1. If the panel group or menu being created contains a matching name on the 
NAME attribute of a HELP tag, the help module is found in the same panel group 
or menu when the Help key is pressed. 


2. If the panel group or menu being created contains a matching name on the 
NEWNAME attribute of an import (IMPORT) tag, the help module is found in the 
panel group specified on the PNLGRP attribute of the IMPORT tag. 


te 


3. If the panel group or menu being created contains an IMPORT tag with NAME= 
specified, the help module is found in the panel group specified on the PNLGRP 
attribute of the IMPORT tag. 
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If all of the above are not true, the UIM compiler reports an error message and the 
panel group or menu is not created. 


When specifying the name of a help module, apostrophes are not necessary unless 
characters other than A through Z, a through z, and 0 through 9 are used. If any 
other keyboard characters are used, apostrophes are required. For example, in a 
name specifying HELP='key/enter'’, the apostrophes are required because the slash 
(/) is not an alphabetic character or a numeral. For more information on the rules 
for names, see “Name Syntax” on page A-4. 


Giving Help Panel Groups Access to InfoSeeker 

InfoSeeker provides access to AS/400 online books. You can give a UIM help 
panel group access to InfoSeeker using the :HLPSHELF parameter on the 
:-PNLGRP tag. Here is an example of the UIM coding to give a help panel group 
access to InfoSeeker: 


:PNLGRP HLPSHELF=LIST. 

HELP. 

SEHELP. 

LEPNLGRP. 

The :HLPSHELF parameter causes the F11=InfoSeeker key to display on the help 
panel for the UIM panel. Pressing F11=InfoSeeker displays the InfoSeeker main 


display as shown in Figure 19-1. The LIST value on the :HLPSHELF parameter 
causes the default list of online books and bookshelves to display. 


InfoSeeker 


Type options, press Enter. 
1=Open 2=Search 4=Remove from view 8=Display description 
9=Put in shelf 11=Update bookshelf 


i=) 
n=] 
ot 


Description 

(S) AS/400 General System Information 
AS/400 Planning and Installation 

(S) AS/400 Operation 

(S) AS/400 System Management 

(S) AS/400 Communications and Connectivity 
(S) AS/400 Using Applications 

AS/400 Application Development 

(S) AS/400 Environments, Program Interfaces, and Enablers 
AS/400 Migration 

(S) AS/400 Service 

(S) AS/400 All System Books 

(S) AS/400 Redbooks 

(B) My Little User's Guide 


* 
= 
n 
YS 


* 
= 
n 
YS 


Pet Shea al Chale Top 


Bottom 
F3=Exit F5=Refresh F6=Change list F9=Command line 
F12=Cancel F13=Sort F17=Position to F24=More keys 


Figure 19-1. InfoSeeker Display 
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Giving Help Panel Groups Access to Index Search 

Index search provides access to user created search indexes. You can give a UIM 
help panel group access to these search indexes using the :SCHIDX parameter on 
the :PNLGRP tag. Here is an example of the UIM coding to give a help panel 
group access to index search: 


:PNLGRP SCHIDX=search index 

S PANEL. 

:EPANEL. 

SEPNLGRP. 

The :SCHIDX parameter causes the F11=Search Index key to display on the help 
panel for the UIM panel. Pressing F11=Search Index displays the index search 


main display as shown in Figure 19-2. The search index specified on the :SCHIDX 
parameter will be the search index displayed on the index search screen. 


Search Index 


Type options, press Enter. (+ indicates an expandable topic) 
5=Display topic 6=Print topic 7=Expand topic 8=Compress topic 


Opt Topic 

Title of this index 

Main Help Topic 

Help number 1 
Help number 3 
Help number 4 

Help number 2 
Help number 3 


Bottom 
Or type search words and press Enter. (* indicates a topic match) 
F3=Exit help F5=All topics F6=Main topics Fll=Hide structure 
F12=Cancel F13=Information Assistant F18=More indexes F24=More keys 
Yoon a 


Figure 19-2. Index Search Display 


Giving Help Panel Groups Access to A User-Defined Panel 
Group 

The help panels provides access to a user-created panel group. This user-defined 
panel group object (*“PNLGRP) must be called QGUHISF9, contain a panel called 
USERDEF, be located in the user's library list, and the user must have *USE 
authority to this object. If the above criteria is met, a function key, F9=User defined 
menu will appear on all UIM help and search index panels. This panel group is 
intended to be set up in a menu format (similar to the Information Assistant menu 
that appears when the user presses F13 from a help panel). An example panel 
group would be: 
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: PNLGRP. 
:KEYL NAME=mainkeys help=helpname. 
:KEYI KEY=f1 
F1=Help 

:KEYI KEY=f3 
F3=Exit 

:KEYI KEY=f12 
F12=Cancel 
:KEYI KEY=f24 
F24=More keys 


:KEYI KEY=enter 
:KEYI KEY=help 

:KEYI KEY=print 
: EKEYL. 


:PANEL NAME=userdef HELP=helpname KEYL=mainkeys TOPSEP=sysnam 


:TOPINST.To select one of the following, type its number below and 


press Enter: 


HELP=helpname ACTION='help'. 


HELP=helpname ACTION='exit' VARUPD=no. 


HELP=hel pname 
HELP=hel pname 
HELP=hel pname 


HELP=hel pname 
HELP=hel pname 


ACTION='cancel' VARUPD=no. 
ACTION='morekeys'. 
ACTION='enter'. 


ACTION='help'. 
ACTION='print'. 


ENTER='MSG CPD9817'. 
User's Info Assist Menu 
:MENU DEPTH='*' BOTSEP=space SCROLL=no. 


:MENUI 

Display user's library list 
:EMENU. 

:OPTLINE.Type a menu option below 
:EPANEL. 


:HELP name=helpname.Option 1 - Help 


help text for given help name 
:EHELP. 
: EPNLGRP. 


Removing Access to F18=More Indexes 


HELP=helpname OPTION=1 ACTION='cmd dsplibl'. 


To not allow users the ability to change the search indexes they are using, create a 
data area called QUHISF18 in the user's library list. The user must have at least 


“USE authority to this data area. Creating this data area will condition off the 
F18=More indexes function key on the Search Index panel. 


Help in a List Area 


A list area displays the contents of a UIM list. The list consists of rows and 
columns of variable information, which appear in a table format. The following 
screen is an example of a panel using a list area to display a list of eight rows. 


For this panel, the user may enter numbers 2, 4, 5, 7, or 8 in the Opt column to 


specify an action to be performed against one of the rows in the list. 


— 


Spooled Files 


Type options, press Enter. 
2=Change 4=Cancel 


Opt File 

fffffffftf 
fffffffftf 
fffffffftf 
fffffffftf 


Nbr 

nnnn 
nnnn 
nnnn 
nnnn 


5=Display 7=Hold 


uv 


CTDUTUT + 


User 

uuuuuuuuUU 
uuuuuuuuUU 
uuuuuuuuuU 
uuuuuuuuUU 


«K 
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8=Release 


Date 
mm/dd/yy 
mm/dd/yy 
mm/dd/yy 
mm/dd/yy 


hh:mm:ss 
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Coding Help 


Help in a list area must be defined at the group level and at the column level for 
columns which are not part of a group. 


Group Level Help 
To define help at the group level, specify the HELP attribute on the list group 
(LISTGRP) tag. This attribute identifies the help module which explains the 
group of columns in the list. 


Column Level Help 
To define help at the column level in a list area, specify the HELP attribute on 
the list column (LISTCOL) tag. This attribute identifies online help information 
which explains the purpose of the column in the list. 


The HELP attribute is not allowed if the column is part of a list column group 
defined by the LISTGRP tag, but is required if the column is not part of a 


group. 
The HELP attribute of the list action (LISTACT) tag identifies the help module 


which explains the list action. The online help information for all active list 
actions is displayed as part of the contextual help for the action column. 


The following source shows how help is defined for the sample panel with a list 

area shown above. All help modules for this sample list area are imported from 

panel group *LIBL/EXAMPL2. When the cursor is positioned on the Opt column, 
the 'splf/option' help module is displayed, followed by these help modules: 


e 'splf/change' 
e 'splf/cancel' 

e 'splf/display' 
¢ 'splf/hold' 

e 'splf/release' 


When the cursor is positioned on either the Date or Time column, the 'splf/created 
date time’ help module is displayed. With the cursor on any other column, the help 
module identified on the LISTCOL tag is displayed. 


:import name='*' pnigrp='*libl/example2'. 


:listact option=2 help='splf/change' enter='call listactpgm'.2=Change 
:listact option=4 help='splf/cancel' enter='call listactpgm'.4=Cancel 
:listact option=5 help='splf/display' enter='call listactpgm'.5=Display 
:listact option=7 help='splf/hold' enter='call listactpgm'.7=Hold 
:listact option=8 help='splf/release'enter='call listactpgm'.8=Release 


:listcol var=option help='splf/option' usage=inout maxwidth=6.0pt 
:listcol var=filenam help='splf/file_name' usage=out maxwidth=12.File 
:listcol var=filenbr help='splf/file_number' usage=out maxwidth=6.Nbr 
:listcol var=usernam help='splf/user_name' usage=out maxwidth=12.User 
:listcol var=filepty help='splf/file_priority' usage=out maxwidth=6.Pty 
:listgrp col=filecrt help='splf/created_date_time'.Created 

:listcol var=filedat usage=out maxwidth=8.Date 

:listcol var=filetiml usage=out maxwidth=8.Time 

:elistgrp. 

:listview cols='option filenam filenbr usernam filepty filecrt'. 
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Help in a Menu Area 


Coding Help 


A menu area contains one or more items, each of which contains an option number 
and a description of an action which can be performed. To select an option, the 
user enters the number of the option on the command or option line and presses 
the Enter key. The following screen is an example of a panel with a menu area. 


This panel has six options the user can choose, and each option has a brief 
description of the action it performs. The option number chosen by the user is 
entered on the Selection line. 


Work with Files 
System: = XXXXXXXX 


Select one of the following: 


. Display file attributes 
. Display file contents 

. Change ownership 

. Change authorizations 

. Delete 

. Backup to tape 


AmnrwWwNr 


Selection 


— — 


Help in a menu area must be defined at the item level. 


Item Level Help 
To define help for a menu area, specify the HELP attribute on the menu item 
(MENUI) tag. This attribute identifies the help module which explains the 
purpose of the menu item. 


The online information identified by the HELP attribute is displayed when help is 
requested while the cursor is positioned on the text for the menu item, or while 
the cursor is on the command or option line and a valid menu item number has 
been entered. 


The following source shows how help is defined for the sample panel shown on 
page 19-7. 


Reference numbers ([fJ) are used in this example to show the relationship 


between referring to a help module using the HELP attribute of a tag, and the defi- 
nition of the help module using the HELP tag. 
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:menui option=1 help='option/display_attr' action='call menuipgm' 
-.Display file attributes 

:menui option=2 help='option/display_cont' action='call menuipgm' 2 | 
.Display file contents 

:menui option=3 help='option/change_owner' action='call menuipgm' 3 | 
.Change ownership 

:menui option=4 help='option/change auth' action='call menuipgm' 4 | 
.Change authorizations 

:menui option=5 help='option/delete' action='call menuipgm' 5 
.Delete 

:menui option=6 help='option/backup_tape' action='call menuipgm' [J 
.Backup to tape 


:help name='option/display_attr' 
.Display File Attributes - Help 
:xh3.1. Display file attributes 
:p.Choose this option to display the attributes associated with this file. 
The attributes include all the information about the definition of the file. 
:ehelp. 
:help name='option/display_contents' [J 
.Display File Contents - Help 
:xh3.2. Display file contents 
:p.Choose this option to display the data contained in this file. 
:ehelp. 
:help name='option/change_owner' 
.Change Ownership - Help 
:xh3.3. Change ownership 
:p.Choose this option to change the owner of this file. 
You are prompted to enter the name of the new owner. 
:ehelp. 
:help name='option/change_auth' 4 | 
.Change Authorizations - Help 
:xh3.4. Change authorizations 
:p.Choose this option to change the list of users 
who have authority to access this file. 
You are prompted for the user names and authorizations for the file. 
:ehelp. 
:help name='option/delete' [J 
.Delete - Help 
:xh3.5. Delete 
:p.Choose this option to delete this file. 
The file and all the data in the file is erased from the system 
and the storage used by the file is made available for other use. 
:ehelp. 
:help name='option/backup tape’ [¥ 
.Backup to Tape - Help 
:xh3.6. Backup to tape 
:p.Choose this option to 
save a copy of this file on a magnetic tape. 
You are prompted for more information about how to back up the 
file on the tape. 
:ehelp. 
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Help in a Data Area 


A data area contains one or more data entry items whose variable information may 
be changed by the user. A data area can also contain output items whose variable 
information can be viewed by the user but cannot be changed. The following 
screen is an example of a panel with a data area. 


— 


Sample Entry Panel 


Type choices, press Enter: 


File name ..... Name of document to be printed 


Type style for 
printing. .... 1 1=Prestige Elite (12 pitch) 
2=Courier (10 pitch) 
3=Essay Standard (proportional) 
4=Essay Bold (proportional) 


Help in a data area must be defined for every item at one of three levels. 


Area Level Help 


To define help at the area level, specify the HELP attribute on the data presenta- 
tion area (DATA) tag. This attribute identifies the help module which explains 
all items in the area. 


If no HELP attribute is specified on the DATA tag, a help module name must be 
associated with each item in the area by specifying the HELP attribute on the 
data group (DATAGRP), the data item (DATAI), and data selection field 
(DATASLT) tags. 


To provide the user with easy access to the online information for a data area 
with the LAYOUT=HORIZ attribute specified on the DATA tag, specify the HELP 
attribute on the DATA tag instead of the HELP attribute on the individual DATAI 
tags. 


Group Level Help 


To define help at the group level, specify the HELP attribute on the DATAGRP 
tag. This attribute identifies the help module that explains all items in the 
group. 

If no HELP attribute is specified on the DATA tag or on any outer or nested 


DATAGRP tags, the HELP attribute is required on all DATAI and DATASLT tags 
within the group. 


Item Level Help 


To define help at the item level, specify the HELP attribute on the DATAI or 
DATASLT tag. This attribute identifies the help module that explains the data 
item or selection field. 


If no HELP attribute is specified on the DATA tag or on DATAGRP tags con- 
taining a data item, the HELP attribute is required on the DATAI and DATASLT 
tags. 


To provide the user with easy access to the online information for a 
LAYOUT=HORIZ data area, use the HELP attribute on the DATA tag instead of the 
HELP attribute on the individual DATAI tags in the horizontal area. 
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The HELP attribute applies to all data item extender (DATAIX) tags associated 
with a data item. 


If the HELP attribute is specified on the DATASLT tag, the HELP attribute can 
also be specified for each choice on the DATASLTC tag. If the HELP attribute is 
specified on a DATASLTC tag within a selection field, all DATASLTC tags 
within that selection field must have the HELP attribute specified. 


For multiple-choice selection fields, the online information identified for each 
choice is included as part of the contextual help displayed when the cursor is 
positioned anywhere within the selection field. 


For single-choice selection fields, the online information identified for each 
choice is displayed when help is requested while the cursor is positioned on the 
text of the choice. This online information is also included as part of the con- 
textual help displayed when the cursor is positioned within the selection field 
but not on the text for one of the choices within the field. This includes occur- 
rences when the cursor is positioned on the prompt text for the selection field 
or in the entry field for the selection field. If the cursor is in the entry field and 
a valid choice is entered, when help is requested, the help for that choice is 
displayed. 


Coding Help 
The following source shows how help is defined for the sample data area panel 


shown previously. All the help modules for this sample data area are imported 
from panel group *LIBL/DATAXMP. 


:import name='*' pnigrp='*libl/dataxmp'. 


:datai var=filename help='print/filename' usage=inout.File name 
:datac.Name of document to be printed 

:datai var=typestyle help='print/style' usage=inout.Type style for printing 
:datac.1=Prestige Elite (12 pitch) 

:datac.2=Courier (10 pitch) 

:datac.3=Essay Standard (proportional) 

:datac.4=Essay Bold (proportional) 

:datai var=leftmarg help='print/left_margin' usage=inout.Left margin 
:datac.Number of spaces from the left edge of the paper (1-20) 
:datai var=copies help='print/copies' usage=inout.Copies 
:datac.Number of copies (1-99) 

:datai var=duplex help='print/duplex' usage=inout.Duplex 
:datac.1=Yes (Print both sides of paper) 

:datac.2=No (Print one side only) 


The following source defines the help modules in panel group *LIBL/DATAXMP. 
These help modules are imported when the Help key is pressed for the previous 
sample data area. 
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shelp name='print/filename'.File Name - Help 


:xh3.File name 


:p.Enter the name of document to be printed. 


:ehelp. 


shelp name='print/style'.Type Style for Printing - Help 
:xh3.Type style for printing 
:p.Enter one of the following to select the type style. 


sparml. 


12 pitch elite style is used. 


A 
2 
:pd.A 10 pitch courier style is used. 
3 
A proportional essay standard style is used. 
4 


:pd.A proportional essay bold style is used. 


:xh3.Left margin 


name='print/left_margin'.Left Margin - Help 


:p.Enter a number from 1 to 20 for the number of spaces from 
the left edge of the paper to the beginning of the printed text. 


:ehelp. 


:help name='print/copies'.Copies - Help 
:xh3.Copies 
:p.Enter a number from 1 to 99 for the number of copies of the 
document to be printed. 


:ehelp. 


:help name='print/duplex'.Duplex - Help 
:xh3.Duplex 
:p.Enter one of the following to select whether or not to print on 
both sides of the paper. 


:parml. 


spt.1 
:pd.Print text on both sides of the paper. 
spt.2 
:pd.Print text only on one side of the paper. 


separml. 
:ehelp. 


The following example panel shows the file name and library name in a data area 
with a horizontal layout. 


— 


File: 


FILEQ1 


Work with File Members 


Library: QGPL 
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The following source shows how help is defined for the sample data area shown 
above. This is an example of providing area level help. When the cursor is posi- 
tioned anywhere on the line containing the file name, help for the file name and 
library are displayed. 


Reference numbers ([fJ) are used in this example to show the relationship 
between a reference to a help module using the HELP attribute of a tag, and the 
definition of the help module using the HELP tag. 


:data depth=2 help='file_and_library' layout=horiz. 
:datai var=filename usage=out.File 

:datai var=library usage=out.Library 

:edata. 


:help name='file_and_library'.File and Library - Help fq 

:xh3.File and library 

:p.The qualified name of the file whose members are being displayed. 
:ehelp. 


The following example panel shows a qualified file name and a record name ina 
data area with a two-column, vertical layout. 


(— —) 


Work with Field Definitions 


PUT Oe ote oy tele FILE Record. .... MASTERO1 


The following source shows how help is defined for the sample data area shown 
above. This includes providing group level help for the qualified file name. When 
the cursor is positioned on the file or library, help for the qualified file name is dis- 
played. When the cursor is positioned on the record name, help for the record 
name is displayed. 


Reference numbers ([fJ) are used in this example to show the relationship 
between referring to a help module using the HELP attribute of a tag, and the defi- 
nition of the help module using the HELP tag. 


:data depth=3 layout=2. 

:datacol width=16. 

:datacol width='*'. 

:datagrp grpsep=qindent help='library/file' compact. [J 
:datai var=filename usage=out.File 

:datai var=library usage=out.Library 

:edatagrp. 

:datai var=record help=record usage=out.Record [y 
:edata. 
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shelp name='library/file'.File and Library - Help 
:xh3.File and library 
:p.The qualified name of the file whose field definitions are displayed. 


:ehelp. 

:help name=record.Record - Help 

:xh3.Record 

:p.The name of the record whose field definitions are displayed. 
:ehelp. 


Help in a Menu Bar Area 


A menu bar area is located at the top of the panel and contains choices which give 
the user access to actions available for the panel. To select a choice in the menu 
bar, the user positions the cursor on the desired choice and presses the Enter key. 
After the user selects a choice in a menu bar, a pull-down menu appears below the 
menu bar containing choices for actions against the panel. 


This partial screen contains an example of a menu bar area. The menu bar is the 
line near the top of the panel, listing File and Help as choices for the user. The 
user may select one of the choices to display the pull-down menu for that choice. 
The second screen in this example shows the pull-down menu displayed after 
selecting File. 


File Help 
Work with Programs 
System: ROCHO001 
Type choices, press Enter. 
2=Change 4=Delete 5=Display 


Opt Program Library Text 

PPPPPPPPPP LLLLLLLLLL Description textxxxxxXxxXXxXXXXXXXXXXXXXXXXXXXXXXKX 
PPPPPPPPPP LLLLLLLLLL Description textxxxxxXxxXXXXXXXXXXXXXXXXXXXXXXXXXX 
PPPPPPPPPP LLLLLLLLLL Description textxxxxxXxxXXxXXXXXXXXXXXXXXXXXXXXXXKX 


When File is selected, a pull-down menu appears containing choices for actions for 
the panel. The actions available in the pull-down menu are Change, Delete, 
Display, and Exit. A pull-down menu with another list of actions appears when the 
user selects the Helo menu bar choice while in the menu bar. 


(— = 
File _Help 
2. Change : Work with Programs 
: System: ROCHO001 
4. Delete : er. 
5. Display : 5=Display 
} 6. Exit F3)? 8 
LELLER CSET CCST ENTS ES Text 


PPPPPPPPPP LLLLLLLLLL Description textxxxxxXxxXxXXXXXXXXXXXXXXXXXXXXXXKX 
PPPPPPPPPP LLLLLLLLLL Description textxxxxxXxxXXxXXXXXXXXXXXXXXXXXXXXXXKX 
PPPPPPPPPP LLLLLLLLLL Description textxxxxxXxxXxXXXXXXXXXXXXXXXXXXXXXXXKX 


Contextual help for a menu bar choice includes help for the choice on the menu 
bar, as well as help for each active choice in the pull-down menu for that menu bar 
choice. Help in a menu bar area must be defined at the menu bar choice level and 
at the pull-down choice level. 
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Menu Bar Choice Level Help 
To define help at the menu bar choice level, specify the HELP attribute on the 
menu bar choice (MBARC) tag. This attribute identifies the help module which 
explains the purpose of the menu bar choice. 


Pull-Down Choice Level Help 
To define help at the pull-down choice level, specify the HELP attribute on the 
pull-down field choice (PDFLDC) tag. This attribute identifies the help module 
which explains the purpose of the pull-down choice. 


Coding Help 
The following source shows how help is defined for the first menu bar choice and 
the pull-down menu shown on page 19-13. 


Reference numbers ([fJ) are used in this example to show the relationship 
between referring to a help module using the HELP attribute of a tag, and the defi- 
nition of the help module using the HELP tag. 


:mbarc help='mbarpgm/file'.File 

:pdfild. 

:pdfldc option=2 help='mbarpgm/file/change' [J 
action='cmd ?CHGPGM PGM(&var2./&varl1.)' 
actfor=list.Change 

:pdfldc option=4 help='mbarpgm/file/delete' 
action='cmd DLTPGM PGM(&var2./&varl.)' 
actfor=list confirm=confpgm usrexit='call exitpgm'.Delete 

:pdfldc option=5 help='mbarpgm/file/display' [J 
action='cmd DSPPGM PGM(&var2./&varl.)' 
actfor=list.Display 

:pdfldc option=6 help='mbarpgm/file/exit' action='exit set' [J 
varupd=no.Exit 

:pdaccel .F3 

sepdfld. 

sembarc. 


:help name='mbarpgm/file'.File - Help 

:xh3.File 

:p.Select this choice to display a pull-down menu containing options 
to perform against selected programs. 

:ehelp. 

:help name='mbarpgm/file/change'.Change - Help [—q 
:parml. 

:pt.Change 

:pd.Choose this option to change attributes of the selected 
programs. 

This choice is not available if no programs were selected 
from the list. 

:eparml. 

:ehelp. 

:help name='mbarpgm/file/delete'.Delete - Help 
sparml. 

:pt.Delete 

:pd.Choose this option to delete the selected programs. 
This choice is not available if no programs were selected 
from the list. 

separml. 
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:ehelp. 

:help name='mbarpgm/file/display'.Display - Help [J 
:parml. 

:pt.Display 

:pd.Choose this option to display the attributes of the selected 
programs. 

This choice is not available if no programs were selected 
from the list. 

separml. 

:ehelp. 

shelp name='mbarpgm/file/exit'.Exit - Help [J 

sparml. 

spt. Exit 

:pd.Choose this option to end the current task and return 
to the display from which the task was started. 

separml. 

:ehelp. 


Help in a Function Key Area 


A function key area is located at the bottom of the panel and contains descriptions 
of the actions available to the user when the user presses a function key. The 
function key area appears on most panels. 


The following partial screen contains an example of a function key area for function 
keys F3, F4, F9, and Fi2. The descriptions for these keys are listed in the function 
key area, which contains the text F3=Exit, F4=Prompt, F9=Retrieve, and 

F12=Cancel 


Selection or command 
===> 


F3=Exit F4=Prompt F9=Retrieve  F12=Cancel 


Contextual help for the function key area includes help for the entire list of keys, as 
well as help for each active function key. This includes function keys which do not 
have text displayed on the panel. Help in a function key area can be defined at the 
area level and must be defined at the item level. 


Area Level Help 
To define help at the area level, specify the HELP attribute on the key list 
(KEYL) tag. This attribute identifies the help module which explains the 
purpose of the function key area as a whole. 


Item Level Help 
To define help at the item level, specify the HELP attribute on the key item 
(KEYI) tag. This attribute identifies the help module which explains the purpose 
of the function key. 
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Coding Help 
The following source shows how help is defined for the function key area shown on 
page 19-15. The help module, fkey, contains no help information. This help 
module only provides a title for contextual help for the function key area and a 
heading for the function keys in extended help. There is no title or extended help 
heading tag in the help for each function key because the contextual help is for the 
entire function key area, not for an individual key. 


Reference numbers ([fJ) are used in this example to show the relationship 
between referring to a help module using the HELP attribute of a tag, and the defi- 
nition of the help module using the HELP tag. 


:keyl name=keys help=fkey. 

:keyi key=f3 help='fkey/exit' action='exit set' varupd=no.F3=Exit 2. 
:keyi key=f4 help='fkey/prompt' action=prompt.F4=Prompt [fq 

:keyi key=f9 help='fkey/retrieve' action=retrieve.F9=Retrieve 4 | 
:keyi key=f12 help='fkey/cancel' action='cancel set' varupd=no.F12=Cancel 5 | 
:keyi key=enter help='fkey/enter' action=enter. 

:keyi key=help help='fkey/help' action=help. 

:keyi key=pagedown help='fkey/pagedown' action=pagedown. 8 | 

:keyi key=pageup help='fkey/pageup' action=pageup. [J 

:keyi key=print help='fkey/print' action=print. 

:ekeyl. 


shelp name='fkey'.Function Keys - Help 

:xh3.Function keys 

:ehelp. 

:help name='fkey/exit'. fj 

:parml. 

spt. F3=Exit 

:pd.Ends the current task and returns you to the display from 
which the task was started. 

:eparml. 

:ehelp. 

shelp name='fkey/prompt'. 

:parml. 

:pt.F4=Prompt 

:pd.Provides assistance in entering or selecting a command. 
separml. 

:ehelp. 

:help name='fkey/retrieve'. [J 

:parml. 

:pt.:F9=Retrieve 

:pd.Shows the last command you entered on the command line, 
along with any parameters you included. By pressing this key 
once, you receive the last command you ran. By pressing this 
key twice, you receive the next to last command that you ran, 
and so on. 

:eparml. 

:ehelp. 

:help name='fkey/retrieve'. [J 

:parml. 

:pt.F12=Cancel 

:pd.Returns to the previous menu or display. 

:eparml. 

:ehelp. 
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:help name='fkey/enter' [J 

:parml. 

:pt.Enter 

:pd.Submits information on the display for processing. 
separml. 

:ehelp. 

shelp name='fkey/help' 

:parml. 

:pt.Help 

:pd.Provides more information about using the display. 
separml. 

:ehelp. 

:help name='fkey/pagedown' [jy 

:parml. 

:pt.Page Down or Roll Up 

:pd.Moves forward to show additional information for this display. 
:eparml. 

:ehelp. 

shelp name='fkey/pageup' 9 

:parml. 

:pt.Page Up or Roll Down 


:pd.Moves backward to show additional information for this display. 


separml. 

:ehelp. 

shelp name='fkey/print' 
:parml. 

spt.Print 


:pd.Prints the information currently shown on the display. 
:eparml. 
:ehelp. 
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Chapter 20. Defining Online Help Information 


When the Help key is pressed and the DDS source for your display file specifies 
that online help information is available for the display, the system shows the infor- 
mation referred to by the panel group or document or, if you used DDS, contained 
in the record. 


The following sections in this chapter tell you how to create the actual information 
that the user sees: 


¢ “Defining Online Help Information in a Panel Group” 


For more information on creating online help using the UIM, see Chapter 19, 
“Making Online Help Accessible for Your Panel Group” on page 19-1 and 
Part 3, “Programming Application Displays Using Panel Groups” on page 14-5. 


¢ “Defining Online Information in a Document” on page 20-18 
¢ “Defining Online Help Information in a DDS Record” on page 20-19 


If the DDS source for your display does not specify that online help information is 
accessible for your display, go to Chapter 18, “Making Online Help Information 
Accessible for Your Display File.” 


Defining Online Help Information in a Panel Group 


The user interface manager (UIM) uses panel groups to access online help infor- 
mation. The online help information in panel groups may be used in several ways: 


e Display help 
¢ Command help 
e Index search topics 


To use panel groups for online help information, you must specify them in the DDS 
source for your application display. If you plan to use panel groups for help but 
have not yet specified them in your DDS source, see “Specifying Panel Groups for 
Help in Your Display File” on page 18-6. 


Entering the UIM Source for a Panel Group for Help 


© Copyright IBM Corp. 1997 


Like display files that are created by compiling DDS source, panel groups are 
created by compiling UIM source. The UIM source for a panel group is entered in 
a source file member. The source type for all panel groups is *PNLGRP. Steps for 
creating and entering data in a source file member are found in Chapter 1, 
“Building a Sample Display with Online Help Information.” 


UIM tags, which always begin with a colon (:) and end with a period (.), are used to 


help format and identify the information. Detailed information about UIM tags is 
found in Appendix A, “UIM Panel Group Definition Language.” 
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Organizing a Panel Group with Help Modules 

The UIM source for every panel group, whether used for display help, command 
help, or an index search topic, starts with a :PNLGRP tag and ends with an 
-EPNLGRP tag. 


Units of help information, known as help modules, are defined in the panel group 
between the :PNLGRP and :EPNLGRP tags. Each help module starts with a 
named :HELP tag and ends with an :EHELP tag, as follows: 


:PNLGRP. 

:HELP name=firsthelp.Title of First Help Module 
2P. 

Information for first help module 

:EHELP. 

:HELP name=secondhelp.Title of Second Help Module 
=P. 

Information for second help module. 

:EHELP. 

:EPNLGRP. 


A panel group may contain one or more help modules. The help module name, 
which is the value for the name attribute on the :HELP tag, identifies the help 
module and must be unique for each help module in the panel group. The text that 
follows the period (.) on the :HELP tag is used as the title when the online help 
information is displayed. 


Using the Information in a Help Module More Than Once 

The :IMHELP tag allows information to be imbedded, which means that information 
that is used more than once can be defined in one help module and then used 
within another help module, as follows: 


: PNLGRP. 

:HELP name=pacific.Pacific Ocean 

:P. 

The Pacific Ocean is the largest ocean in the 
world. 

: IMHELP name=ocean. 

:EHELP. 

:HELP name=atlantic.Atlantic Ocean 


£P. 

The Atlantic Ocean separates North and South America from 
Europe and Africa. 

: IMHELP name=ocean. 

:EHELP. 

:HELP name=ocean. 

:P. 

An ocean is one of the five large bodies of salt water, which 
together cover nearly three-fourths of the world. 

:EHELP. 

:EPNLGRP. 


Note: The :P tag used in the previous UIM source indicates the start of a para- 
graph. More information on the :P tag is available in Appendix A, “UIM 
Panel Group Definition Language.” 


20-2 Application Display Programming V4R1 


When the user sees the online help information in the previous example, the defi- 
nition of ocean is the second sentence for the definitions of both the Pacific Ocean 


and the Atlantic Ocean. 


Using a Help Module Contained in a Different Help Panel Group 
If the help module that contains the repeated information is contained in a different 
panel group, an :IMPORT tag is needed. The :IMPORT tag identifies the panel 

group that contains the needed help module and makes that panel group available 


for use within the current panel group. The :IMPORT tag is placed after the 


:PNLGRP tag and before the first :HELP tag in the panel group that refers to the 


help module. 


First panel group (named PNLSAM1): 


:PNLGRP. 

: IMPORT pnigrp=pnlsam2 name=ocean. 

:HELP name=pacific.Pacific Ocean 

=Pe 

The Pacific Ocean is the largest ocean in the 
world. 

: IMHELP name=ocean. 

:EHELP. 

:HELP name=atlantic.Atlantic Ocean 

HP 

The Atlantic Ocean separates North and South America from 
Europe and Africa. 

: IMHELP name=ocean. 

:EHELP. 

:EPNLGRP. 


Second panel group (named PNLSAM2): 


: PNLGRP. 

:HELP name=ocean. 

Pi 

An ocean is one of the five large bodies of salt water, which 
together cover nearly three-fourths of the world. 


: EHELP. 

:EPNLGRP. 
Panel group Panel group 
PNLSAM1 PNLSAM2 


sHELP name = pacific. 
. ; HELP name = ocean. 


¢HELP name = atlantic. 


RV2W056-2 
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Emphasizing and Formatting the Text within a Help Module 

Panel markup tags are UIM tags used within help modules to help format and 
emphasize the information. More detailed information about the panel markup tags, 
including examples that show how the tags are used, is found in Appendix A, “UIM 
Panel Group Definition Language.” 


Defining Paragraphs and Notes: The following panel markup tags format blocks 
of text into paragraphs or notes: 


Function UIM Tags Use 
Notes ‘NT and :ENT A note with one or more paragraphs. A note begins 
:NOTE and with Note: and usually refers to something in the text 
:-ENOTE that precedes it. Displayed note text is indented. 
Paragraphs :P A block of text that forms a paragraph. Paragraph 
text is separated from other paragraphs and text by 
a blank line. 
Paragraph :PC Continuation of a paragraph that has been inter- 
continuation rupted by another panel markup tag, such as a 


figure, example, or list. When you specify paragraph 
continuation for text, paragraph formatting returns. 


Adding Headings: The following panel markup tags identify associated text as 


headings: 

Function UIM Tags Use 

Extended help *XH1 through :XH4 Conditional headings for main topic and 

headings subtopics of information. (When displaying 
contextual help, the first extended help 
heading tag is ignored so that its text is not 
shown.) Headings are useful for separating 
and organizing sections of text. Displayed 
heading text is highlighted and placed on its 
own line. 

Headings ‘H1 through :H4 Main topics and subtopics of information. 


Headings are useful for separating and 
organizing sections of text. Displayed 
heading text is highlighted and placed on its 
own line. 


Highlighting Text: The following panel markup tags allow you to highlight text: 


Function UIM Tags Use 

Highlighted phrases ‘HPO through :HP9 A word or phrase to be highlighted. Text 
and :EHPO through may be highlighted to emphasize it from the 
‘-EHP9 surrounding text. Depending on the tag, 


displayed highlighted text may be shown 
normal, underlined, brightened or colored 
differently, in reverse image, or a combina- 
tion of these effects. 


Title Citation :CIT and :ECIT The title of a publication. Publication titles 
are underlined when displayed. 
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Making Lists: 
markup tags: 


You may organize your text in lists using the following panel 


Function 
Definition List 


List part 


Ordered list of items 


Parameter list 


Simple list 


Unordered list 


UIM Tags 

‘DL and :EDL 
(starts and ends 
list); :DTHD and 
:DDHD (provides 
column headings): 
‘DT and :DD (iden- 
tify terms and their 
definitions) 


‘LP 


:OL and :LI and 
‘EOL 


:PARML and 
‘-EPARML 


:SL and :LI and 
‘ESL 


‘UL and :LI and 
‘-EUL 


Use 

A list of words or phrases and their corre- 
sponding definitions, descriptions, or expla- 
nations. When definition lists are displayed, 
each term appears in the left column with its 
definition across from it in the right column. 


A comment or explanation that applies to a 
part of a list. A list part allows you to enter 
text after a list item without making the text 
part of the previous list item and without 
interrupting the list. List part text is not 
indented when displayed. 


An ordered list of items. Items in an 
ordered list are preceded by numbers or 
alphabetic letters to show sequence or 
order. Displayed list items in an ordered list 
are indented. 


Parameter terms and descriptions. The 
parameter list is commonly used to define 
programming keywords and variables. The 
parameter term is shown in the left column; 
its definition appears indented on the line 
following the term. 


List of items. Simple lists are commonly 
used when list items are contained on one 
line and no sequence is required. List items 
in a simple list are indented only and not 
preceded by numbers, letters, hyphens, or 
dashes. 


Unordered list of items. Unordered lists are 
commonly used when sequence is not 
required for the items in the list. List items 
in an unordered list are indented and pre- 
ceded by the lowercase letter 0, a hyphen, 
or a dash. 


Identifying Programming Keywords and Variables: The following panel markup 
tags allow you to highlight programming keywords and variables, and are often 
used with the parameter list tags: 
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Function UIM Tags Use 

Programming :PK and :EPK A programming keyword. Programming 

keyword keywords are used to explain the elements 
of programming syntax. Programming 
keywords are highlighted and, if specified as 
a default also, underlined. 

Programming vari- :PV and :EPV A programming variable. Programming vari- 

able ables are used to explain the elements of 
programming syntax. Programming vari- 
ables are underlined when displayed. 


Indicating Structured Text: \f you want text to be displayed as it is entered, you 
can use the following panel markup tags: 


Function UIM Tags Use 

Example :XMP and :EXMP An area of text that is displayed exactly as it 
is entered. Examples are commonly used 
to show sample computer input or output. 
Displayed example text is indented. 


Figures ‘FIG and :EFIG A diagram, chart, or other illustration. If 
desired, figures may be displayed with cap- 
tions. 

Unformatted lines :LINES and An area of text that is displayed exactly as it 

-ELINES is entered. Unformatted lines are used for 


any text that needs to be displayed without 
being concatenated. 


For more information on the language tags, see Appendix A, “UIM Panel Group 
Definition Language” on page A-1. 


Adding Index Search Tags to a Help Panel Group 

Help panel groups may also contain index search modules. Index search supple- 
ments the help information that is provided for each display. To use the information 
in help panel groups for the index search function, you need to add the appropriate 
UIM tags to your help modules. 


Understanding How Index Search Works: Users can access the index search 
function from any display help that specifies that the index search function is avail- 
able. 


When the user presses the Help key from a working display, help information is 
displayed. On all help displays that support the index search function, F11=Index 
search is active. When the user presses F11, the Index Search display appears. 
This display shows a list of main topics in the topic hierarchy. It has an input field 
at the bottom for search words. 


The user can browse or print any topic in the list or type a word (or words) on the 
input field. To view one or more topics, the user types a 5 in the option field beside 
the topic title and presses the Enter key. To print one or more topics, the user 
types a 6 in the option field. 


A plus sign (+) next to a topic means that the user can expand the topic to show its 
subtopics in the hierarchy using option 7 (Expand topic). Or, the user can use 
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option 8 (Compress topic) to compress a topic so that the subtopics are no longer 
shown. 


If the user types a word or words on the input field, the index search function 
matches the words with synonym tables, and presents a list of topics that match 
the search words entered. 


The following illustration shows how the index search function is accessed from 
display help: 
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Application Display 


Bookkeeping 


Amount.... 


Receivable 


Owed 


Net 


User presses Help key 


’ 


Help Display 

HELP Receivable 

XXXXXKXXXKXXKXIHXKX XXX KAXK 
XXXXXKXXNXKX XXXXXKXKXX 
XXKIK — CUFSOF—_YYXXXXXXXX 
XXXXXXXXXX seneile XXXXXXXXXX 
XXXXXXXXXX  7@!P XXXXXXXXXX 
XXXXXKXXXX XXXXXXXXXX 


XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXKX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX, 


If using UIM help facility 


User presses Index Search key 


| 


User presses Help key 


: 


Index Search 


Select topic: 

Topic A 

Topic B 

Topic C 
Enter words to find 
Topic D 


How to Use Help 


Types of 
help and how 
to get it 


User 
enters 
search 
words 


Index Search 


HELP Glossary 
XXXXXXXXXXXXXXXKXXXXXKXKXXKKK 


Select topic: User XXXXXXXXXXXXXXXXXXXXXXXXXX 

Topic D F XXXXXXXX ‘on XXXXXXXXX 
Inf 

dis p lay XXXXXXXX Aho (ene XXXXXXXXX 

topic XXXXXXXX XXXXXXXXX 


Enter words to find 
Topic D 


XXXXXXXXXXXXXXXXXXXXXXXXXK 
XXXXXXXXXXXXXXXXXXXXXXXXXK 
XXXXXXXXXXXXXXXXXXXXXAXXXXK 


& 
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The user may also reach the index search function by using the Start Search Index 
(STRSCHIDX) command. The STRSCHIDX command lets a user access search 
indexes without using the Help key or F11. 
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Deciding Which Topics to Put in Index Search: \|ndex search topics usually 
consist of conceptual, procedural, and reference information. 


Conceptual information usually answers the question “Why?” Conceptual informa- 
tion includes overviews, rationales, advantages, comparisons and contrasts, and 
diagrams. 


Procedural information answers the question “How do |... ?” Procedural informa- 
tion always consists of a series of steps. 


Reference Information typically answers the question “What is . . . ?” Reference 
information includes definitions, examples, commands, tables, prerequisites, and 
cautions. 


Defining Index Search Topics and Root Words: The :ISCH tag defines the title 
of a topic in the index and specifies the root words that serve as the link between 
the topic and the search words (synonyms) entered by the user. The tag appears 
immediately after the :HELP tag to which it refers. There can only be one :ISCH 
tag within a single help module. 


For each :ISCH tag, there can be several lines of root words, provided that the total 
number of root words is no more than 50. If more than one line of root words is 
used, ROOTS= must be repeated at the beginning of the second line and subsequent 
lines: 


:PNLGRP. 

:HELP name=entryl. 

:ISCH ROOTS='rootl root2 root3 root4 root5' 

ROOTS='root6 root7 root8 root9 rootl0' 

ROOTS='root11 root12 rootl3 ... root50'. 

Title of First Topic 

“Ps 

This is the first index search module in this panel group. 
:EHELP. 

:EPNLGRP. 


The root words on all lines must be enclosed in apostrophes and a period must be 
placed only at the end of the last line of root words. The topic title follows the 
period on the :ISCH tag and may be placed on the line immediately following the 
period. 


Designating Synonyms for Root Words: The :ISCHSYN tag defines the words 
(synonyms) that, if entered by a user, match a specific root word. If a word that is 
entered by a user is a synonym for a root word, then a match is found for each 
topic whose :ISCH tag contains that root. 


If you want a word that is used as a root word to be used as a synonym as well, 
you must include the word as a synonym on the :ISCHSYN tag. For example: 


: ISCHSYN ROOT='ocean'.ocean water sea 
The synonyms for the :ISCHSYN tag must be entered on one line, and at least one 


:ISCHSYN tag must exist for each root word. If more than one line is needed, 
more :ISCHSYN tags may be entered for the same root word. 
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UIM does not differentiate between synonyms entered in uppercase, lowercase, or 
mixed case. For this reason, it is not necessary to repeat synonyms to cover all 
the different cases. 


You may use alphabetic or numeric characters for synonyms; however, the fol- 
lowing characters (including their hexadecimal equivalents) are not allowed to be 
used as a synonym or part of a synonym: 


(period) 

(left parenthesis) 

(right parenthesis) 
: (semicolon) 

(comma) 

(question mark) 

(colon) 


The :ISCHSYN tags may be placed anywhere in the panel group, but to make 
maintenance easier, place them all in one area (such as at the beginning of your 
panel group or in a panel group object that contains only :ISCHSYN tags). 


The following example shows some :ISCHSYN tags and the :ISCH tags that use 
them: 


:PNLGRP. 

: ISCHSYN ROOT='ocean'.ocean water sea 

: ISCHSYN ROOT='lake'.lake water pond 

:ISCHSYN ROOT='definition'.definition define description what 
:ISCHSYN ROOT='definition'.summary concept information explanation 
:HELP name='defocean'. 

:ISCH ROOTS='definition ocean'. 

Definition of ocean 

:P. 

An ocean is one of the five large bodies of salt water, which 
together cover nearly three-fourths of the world. 

:EHELP. 

:HELP name='deflake'. 

:ISCH ROOTS='definition lake’. 

Definition of lake 

$P. 

A lake is a body of standing water that is enclosed by land. 
:EHELP. 

:EPNLGRP. 


Choosing Root Words and Synonyms for Index Search Topics: The following 
tips help you decide which words to use as root words and synonyms for your 
index search topics: 


e Design the root words as building blocks that can be put together in different 
combinations for different topics. 


e The significant words in the title of a topic provide a good start on an appro- 
priate set of root words for the topic. 


e Use only one form of a word as a root word if all forms of the word have the 
same synonyms. 


e If two similar words have the same synonyms, use only one of the words as a 
root word, not both. 
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e There will be cases where it is appropriate to use two separate root words that 
have many common synonyms. 


e Include all synonyms that seem reasonable for the root word. 


e¢ Remember that the root words are only used to connect synonyms with help 
topics. 


e You may have to create a special root word that applies to only one topic or a 
few specific topics, but these special root words should be the exception, not 
the rule. 


e For topics whose titles include an abbreviation, the abbreviation and the major 
words making up the abbreviation should all be used as root words. 


e Either uppercase or lowercase may be used. 


e Use comment lines liberally to clarify the context in which particular root words 
are to be used. 


e If the root word is a real word, include the same word as a synonym for the 
root word. 


e You may want to include misspellings of commonly misspelled words as syno- 
nyms. 


Defining an Index Search Hierarchy: The index search subtopic (ISCHSUBT) 
tag identifies the help modules within the same panel group that are subtopics 
under the preceding topic specified on an index search (ISCH) tag. The 
ISCHSUBT tag must appear after the ISCH tag. Any help module that is not identi- 
fied by an ISCHSUBT tag is a primary topic in the index search hierarchy. There- 
fore, if no ISCHSUBT tags are used, all help modules are primary topics and there 
is no hierarchy. 


The TOPIC attribute on the ISCHSUBT tag is used to define the subtopics for a 
topic. The order in which the help modules appear on the TOPICS attribute is the 
order in which they are displayed in the index search hierarchy. For more informa- 
tion on the rules for help module names, see “Name Syntax” on page A-4. 


A topic can be the subtopic of more than one topic. 
Topics can be nested to no more than 16 levels. 


The following example shows how the ISCH tags and ISCHSUBT tags work 
together to form an index search hierarchy: 


:PNLGRP. 

:HELP name=mainhelp. 

:ISCH roots='root words'. 

Main Help Topic 

: ISCHSUBT topics='help1' 
topics='help2'. 


:EHELP. 

:HELP name=help1. 

:ISCH roots='root words'. 

Help number 1 

: ISCHSUBT topics='help3 help4'. 


Chapter 20. Defining Online Help Information 20-11 


:EHELP. 

:HELP name=help2. 

:ISCH roots='root words'. 
Help number 2 

: ISCHSUBT topics='help3' 


:EHELP. 

:HELP name=help3. 

:ISCH roots='root words'. 
Help number 3 


:EHELP. 

:HELP name=help4. 

:ISCH roots='root words'. 
Help number 4 


:EHELP. 
:EPNLGRP. 


This UIM source creates the following index search hierarchy: 


(— = 


Search Index 


Type options, press Enter. (+ indicates an expandable topic) 
5=Display topic 6=Print topic 7=Expand topic 8=Compress topic 


Opt Topic 

Title of this index 

Main Help Topic 

Help number 1 
Help number 3 
Help number 4 

Help number 2 
Help number 3 


Bottom 
Or type search words and press Enter. (* indicates a topic match) 
F3=Exit help F5=All topics F6=Main topics Fll=Hide structure 
F12=Cancel F13=Information Assistant F18=More indexes F24=More keys 
a = 


National Language Considerations: The index search function can be used with 
either double-byte character support (DBCS) or single-byte character support 
(SBCS) data. When DBCS data is used, the device from which it is requested 
must be capable of entering and presenting the data in DBCS. The object which 
contains the index search data is marked as containing DBCS data when appro- 
priate. The system determines if the device is capable of handling the DBCS data. 


When the data is being prepared for DBCS format and the index search function is 
used with that data, consider the following: 


e When the index search data is prepared for a DBCS system, the synonyms 
entered on the ISCHSYN tag must be in double-byte character mode. That is, 
the first byte after the tag must be a shift-out character and the last byte of the 
data must be a shift-in character. The system does not convert data on the 
ISCHSYN tag to double-byte. 
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¢ Words must be separated by a single-byte blank. From 1 to 19 double-byte 
characters may be combined to form a word. Intervening shift-out and shift-in 
characters are allowed, but are ignored by index search. 

¢ The words that are used to link the ISCH and ISCHSYN tags (the ROOTS attri- 
bute of the ISCH tag and the ROOT attribute of ISCHSYN tag) must be identical 
and should not be entered in DBCS. 

¢ Search words can be entered in either single-byte mode or double-byte mode. 
Single-byte blanks can be entered to separate the words. 


When the search words are shown on the screen, the double-byte character repre- 
sentation (the character that was actually used in the search) is shown. Special 
processing takes place so that index search is not case sensitive. The search 
words from the ISCHSYN tag are uppercased using a translation table for the code 
page that is specified with the TXTCHRID attribute of the PNLGRP tag. If the search 
words are DBCS, they are not uppercased. Shift-out and shift-in characters are 
treated as blanks during parsing; leading and trailing blanks are removed. All 
SBCS words are uppercased using a translate table for the code page of the 
device description. For more information on DBCS, see Appendix D, “Double-Byte 
Character Set Support for Displays” on page D-1 


Linking Help Modules 

Hypertext is a structure of related help modules that are linked together by their 
common areas. The linking allows users to select one or more help modules of 
interest from another help module. A help module that links to one or more help 
modules is called an information node. 


Without hypertext, the only way you can access help is through the associated 
display or the command prompter. You cannot go directly from one help module to 
another unless a link, an association between two information nodes, exists that 
makes each help module a node in a hypertext network. 


Display Display Displa 
1 < >» 2 +> 3 pray 


RV2W014-2 


Similarly, the only way you can access an index search topic is through the index 
search function. You cannot go directly from one index search topic to another. 
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Index 
Search 
P- Topic A 
~- Topic B 
~- Topic C 


Topic A Topic C 
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These restrictions make it difficult for you, first, to determine what related informa- 
tion exists and, second, to access the information conveniently. Hypertext makes it 
possible for you to identify relationships among information nodes so that you and 
other users can easily access the information you need. 


Designing Your Links: The structure of your hypertext nodes determines the 
relationships among the different nodes. 


Relationships that involve hierarchy (such as those between a task and its subtasks 
or between a command and its parameters) can be expressed as subordinate 
nodes below a larger node that they relate to, in the same way that an organization 
chart represents the management structure. 


Relationships that do not involve hierarchy (such as those between a procedural 
node and a reference node or between two similar procedures) can be expressed 
as clusters of nodes. 


If you are designing a complex hypertext structure, the following questions may 
help you make design decisions about what to link to what: 


e¢ “What don’t | understand here?” 

e “What words are unfamiliar?” 

e “What conceptual information is assumed?” 

e “What else do | need to know to complete my task?” 

e “What is the next task | want to do after this one?” 

e “What other tasks are similar to this one?” 

e “What would a graphical representation of this information look like?” 
e “What is a specific example of this general information?” 

e “What other displays or commands are related to this one?” 


You are allowed as many links as you want from any one information node; 
however, it is not essential that each information node be linked to another node. 
A link implies a clear logical relationship. If the relationship is not clear and logical, 
no link should exist. 


Creating Links: A hypertext reference phrase is a word or phrase that identifies 
a selectable hypertext link. The reference phrase is emphasized (with high inten- 
sity or color or underlining or a combination of these, depending on the display 
station). The hypertext reference phrase tells the user that there is more informa- 
tion at the other end of the link. 
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To create a hypertext link, use the :LINK tag to mark the beginning of the reference 
phrase. Use the corresponding :ELINK tag to mark the end of the reference 
phrase. 


You define a link in one direction only, from node A to node B. The link back from 
node B to node A is not defined by a :LINK tag. However, the user can return from 
node B to node A by pressing F12. The user can also press F6 to display a list of 
the titles of nodes previously displayed, then position the cursor next to a title on 
that list and press Enter to return to and display the selected node again. 


The following example uses the :LINK tag to create a link from one help module to 
another help module: 


:HELP NAME='wrkjob'.Work with Jobs - Help 

:XH3.Work with jobs 

oP s 

The Work with Jobs display shows you the status of your 
:LINK PERFORM='DSPHELP job pnigrp1'. 

jobs. 

:ELINK. 

:EHELP. 


The following display shows how the preceding example would look to the user: 


(— > 


Work with Jobs - Help 


The Work with Jobs display shows you the status of your jobs. 


Note that the reference phrase is emphasized when displayed. It is also preceded 
by three blanks for an attribute byte, a one-character field, and another attribute 
byte. By using the Tab key to place the cursor on this field, the user can see the 
additional information about the highlighted word or phrase by pressing the Enter 
key. 


Creating and Deleting Panel Groups 


The Create Panel Group (CRTPNLGRP) command creates panel groups for help 
displays. In the following example, the panel group named PNLSAM in library 
LIBSAM is created by using source file member HDMSAM in the same library. 


CRTPNLGRP PNLGRP(LIBSAM/PNLSAM) SRCFILE(LIBSAM/SRCSAM) SRCMBR(HDMSAM) 


The Delete Panel Group command (DLTPNLGRP) deletes panel groups from the 
system. In the following example, the panel group named PNLSAM in library 
LIBSAM is deleted: 


DLTPNLGRP PNLGRP(LIBSAM/PNLSAM) 
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Assigning Panel Groups as Help for Commands 
Panel groups can be created as help for command parameters that may be 
prompted. 


The first help module, which contains extended help for the command, is specified 
for the Help identifier parameter for the Create Command (CRTCMD) command. 
Each additional help item in the panel group corresponds to a parameter in the 
command. Only one help module can exist for each parameter that can be 
prompted. 


For a help module to be associated with a parameter, the :HELP name must use 
the following convention: 


:HELP name='help-identifier/parameter-name'. 


where help-identifier is the name specified for the Help identifier parameter in 
the Create Command (CRTCMD) command, and parameter-name is the name of 
the parameter that the help module describes. 


The following example shows one way to organize a panel group for command 
help: 

:PNLGRP. 

:HELP name=startcmd. 

SP... 

The text for this help module is used as the 

extended help for the command. 

:EHELP. 

:HELP name='startcmd/parameter1'. 

=P. 

This help item is used for information about the first 
parameter. 

:EHELP. 

:HELP name='startcmd/parameter2'. 

=P. 

This help item is used for information about the second 
parameter. 

:EHELP. 

:EPNLGRP. 


Using Panel Groups in a Search Index 
Panel groups that contain :ISCH, :ISCHSYN, and :ISCHSUBT tags can be added 
as entries in a search index. To find out how to access the index search function, 
see “Understanding How Index Search Works” on page 20-6. 


Creating a Search Index 

The Create Search Index (CRTSCHIDX) command creates a search index object. 
Search index entries that provide the reference to the online help information con- 
tained in one or more panel group objects may be added to this object. These 
referenced panel groups can be added and removed from the search index. 


In the following example, a search index object named ACCOUNTING is created in 
the current library: 
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CRTSCHIDX SCHIDX (ACCOUNTING) 
TITLE('Accounting Help Index') 
TEXT('Accounting Help Index') 


Adding Entries to a Search Index 

The Add Search Index Entry (ADDSCHIDXE) command causes a search index 
object to build references to the root words and synonyms for each help module in 
a panel group that contains an ISCH tag. The help modules in the panel group 
then become entries in the search index object. 


When a search index object refers to several panel groups as entries, the order 
that the panel groups are added into the search index object determines the order 
the entries are displayed when search index function is shown. Similarly, the order 
of the help modules in a panel group define the order in which those topics appear 
in the search index. If the panel group defines a hierarchy, then the topics appear 
in the order defined by the hierarchy. 


A limit of 1000 panel groups may be added to a search index object. Only one 
type of panel group may be added to a search index object. That is, a search 
index object cannot contain panel groups that use the ISCHSUBT tag and panel 
groups that do not use the ISCHSUBT tag. 


In the following example, the panel group named PAYROLL is added to the search 
index named ACCOUNTING. Both the panel group object and the search index 
object must exist in the library list. 


ADDSCHIDXE SCHIDX(ACCOUNTING) = PNLGRP(PAYROLL) 


Removing Entries from a Search Index 

The Remove Search Index Entry (RMVSCHIDXE) command removes the refer- 
ences to a panel group from the search index object. The RMVSCHIDXE 
command removes references to a panel group object that was added using the 
ADDSCHIDXE command. 


In the following example, entries for the panel group PAYROLL are removed from 
the search index ACCOUNTING. The search index object is found by searching 
the library list. 


RMVSCHIDXE SCHIDX(ACCOUNTING) | PNLGRP(PAYROLL) 


Deleting a Search Index 

The Delete Search Index (DLTSCHIDX) command deletes a search index object 
from the system. The DLTSCHIDX command does not delete any panel groups 
that are referred to by the search index object. 


In the following example, a search index object named ACCOUNTING is deleted 
from the library where the object is first found in the library list. 


DLTSCHIDX SCHIDX (ACCOUNTING) 
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Copying QUSRTOOL Examples That Define Help in a Panel Group 
The QUSRTOOL library provides sample DDS-described displays that access 
online help information using panel groups. You can copy these examples into a 
library of your choosing and then tailor them for your own use. For more informa- 
tion about these sample displays, see “Using the Displays Example in the 
QUSRTOOL Library” on page 21-1. 


Defining Online Information in a Document 


You can use documents created by the word processing function of AS/400 
OfficeVision to contain the online help information for your display. 


To use documents for online help information, you must specify them in the DDS 
source for your application display. If you plan to use documents but have not yet 
specified them in your DDS source, see “Specifying Documents in Your Display 
File” on page 18-9. 


Online documents used as help information are created using the word processing 
function of the OfficeVision licensed program. You do not need the OfficeVision 
licensed program on your system to run online help information, but you do need 
the licensed program to create an online help document. 


When you create your document, you need to use help information labels to mark 
the specific location in the document where the information is located. 


Creating a Document for Help 
Follow these steps to create a help document: 


1. Create a document to contain the help information source. Create the docu- 
ment using the Create Document (CRTDOC) command. The following example 
shows how to create a document named HELP.DOC in folder HELPFLD: 


CRTDOC DOC(HELP.DOC) FLR(HELPFLD) 


2. Place a help information label instruction at the beginning of the document for 
general information about the application display. To do this, follow these 
steps: 


a. Press F5. 

b. Type .help 

c. Press the Enter key. 

d. Type a label name. 

e. Do not type a document and folder name unless referring to help informa- 
tion that is stored in another document. 


3. Type general information about the display for which you are creating help 
information. This information appears when the Help key is pressed while the 
cursor is not on one of the help areas defined in the DDS for the display. 


4. Perform the following for each individual prompt in the display for which you are 
writing the help information: 


a. Insert a help information label instruction with a label name that describes 
the prompt (for example, CUSTNBR, NAME, ADDR, and STATE). 


b. Type the help information for the prompt immediately following the help 
information label. 
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5. If desired, insert help information label instructions for the following special 
areas of the help information document: 


¢ Insert a help information label called TOC immediately before the table of 
contents instruction (.toc) if your help information document contains a table 
of contents. 


Note: The Outline Heading Instruction (.h) display contains two options 
specifically for help information documents. The Start on new 
display and Show heading text prompts give you greater control 
over where and how your help information appears in the resolved 
help information document. 


e Insert a help information label called INDEX immediately before the index 
instruction (.ix) if your help information document contains an index. 


Note: If you specify Y for the Create help tags prompt on the Index 
Instruction display, help information labels are automatically created 
for each letter section of the index when your document is resolved. 
This allows you to type, for example, the letter s to go directly to the 
index words starting with s when viewing the help document. 


e If your help information document contains a glossary, insert a help infor- 
mation label called GLOSSARY immediately before that section. 


6. When you finish creating your help document source, press F3 (Exit), type Y for 
the Print document and Display print options prompts, and press the Enter key. 

7. Page forward to page three of the Print Options display. 

8. Specify Y for the Save resolved output prompt, specify a unique document 


name for the Document prompt, and also specify the folder where you want the 
help information document stored. 


The resolved document is your help information document. 


More information about using documents in applications is found in the Office Ser- 
vices Concepts and Programmer's Guide. 


Viewing the Document without Pressing the Help Key 


The Display Help Document (DSPHLPDOC) command allows you to display the 
help information document without running an application. This command can be 
entered in one of the following ways: 


¢ Specify the document name and folder in the DSPHLPDOC command to 
display the beginning of the help information document. 


¢ Specify a document name, folder, and label with the DSPHLPDOC command to 
display the help information associated with the specified label. 


Defining Online Help Information in a DDS Record 
You can use DDS records for the online help information for your display. 
The record formats that give the actual online help information may be included in 


the same member as the DDS source for the application display. The record 
formats may also be contained in a different display file. An example of DDS 
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source used for online help information is shown in “Entering the Records That 
Contain the Help Information” on page 18-14. 
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Chapter 21. Designing IBM AS/400-Style Displays 


If you use data description specifications (DDS) to implement your displays, this 
chapter shows the format of each AS/400 system display type, giving the position 
and characteristics of all key display elements, both constants and data fields. In 
addition, this chapter describes the common actions assigned to function keys 
across the AS/400 system. However, if you use the user interface manager (UIM) 
to implement your displays, the UIM provides the correct formatting and placement 
for you. For more information on UIM, see Part 3, “Programming Application Dis- 
plays Using Panel Groups” on page 14-5. 


By using the guidelines in this chapter, your displays will be compatible with the 
Systems Application Architecture* (SAA*) environment, which makes significant use 
of the IBM Systems Application Architecture Common User Access (CUA) rules 
and guidelines that apply to display stations. 


Using the Displays Example in the QUSRTOOL Library 


The purpose of the QUSRTOOL library, which is optionally installable on the base 
operating system, is to provide you access to examples of various tools and pro- 
gramming techniques that may help you with application development and manage- 
ment of your system. 


Before you can use any of these program examples, the save files in which they 
are packaged must first be changed into source physical files. This may have 
already been done for you; if not, an UNPACKAGE tool is provided to do it for you. 
For instructions for unpackaging the files, see member TTTINFO in source physical 
file QATTINFO. (You can use the DSPPFM command to display the physical file 
member.) 


Source physical file QATTINFO contains all the information you'll need to get 
started. For each example program in the QUSRTOOL library, there is a member 
in QATTINFO that describes the tool and how to install it. 


The displays example in the QUSRTOOL library gives you access to four sample 
displays and a sample command. Online information is available for the displays 
and the command and includes the index search function and hypertext links. 


Recognizing the Example Objects 


The sample displays tool in QUSRTOOL is made up of several members that will 
help you install, create, and delete the objects used by the example: 
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Table 21-1. Source Members for Displays Example in QUSRTOOL (Install, Create, and 


Delete) 


Source Member 
T0011INF 


Source 
File 


QATTINFO 


Object 
Type 
N/A 


Description 


Primary documentation member that 
tells you what to do to install the 
example objects in a library of your 
choosing. The documentation may be 
viewed using the DSPPFM command, 
CPYF to a printer, or using the SEU 
display function. 


T0011CRT 


QATTCL 


*PGM 


Installation program for creating all the 
example #1 objects 


T0011CR2 


QATTCL 


*PGM 


Installation program for creating all the 
example #2 objects 


T0011CR5 


QATTCL 


*~PGM 


Installation program for creating all the 
example #3 objects 


T0011DCL 


QATTCL 


*PGM 


Program that shows the example display 
file with its four sample displays, 
command, and online help information 


T0011DLT 


QATTCMD 


*“CMD 


Command to delete all the example 
objects for example #1 


T0011DC2 


QATTCMD 


*“CMD 


Command to delete all the example 
objects for example #2 


T0011DC5 


QATTCMD 


*“CMD 


Command to delete all the example 
objects for example #3 


T0011DEL 


QATTCL 


*PGM 


Program used by the T0011DLT 
command to delete the example objects 
for example #1 


T0011DL2 


QATTCL 


*PGM 


Program used by the T0011DC2 
command to delete the example objects 
for example #2 


T0011DL5 


QATTCL 


*PGM 


Program used by the T0011DC5 
command to delete the example objects 
for example #3 


The sample displays, command, and online help information are contained in the 
following members of QUSRTOOL: 
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Table 21-2. Source Members for Displays Example in QUSRTOOL (Sample Displays, 
Command, and Online Help Information) 


Source Member Source Object Description 
File Type 

T0011CMD QATTCMD | *CMD Sample commands 

T0011CM2 

T0011CM3 

T0011CM5 

T0011CLP QATTCL *PGM Command processing program (CPP) 

T0011CP2 used by the sample command 

T0011CP3 

T0011CP5 

T0011CHL QATTUIM *PNLGRP Online help information for the sample 
command 

TOO11DDS QATTDDS *FILE Example display file that contains the 
DDS source for a sample AS/400-style 
menu, entry display, information display, 
and list display 

T0011DHL QATTUIM *PNLGRP Online help information for the example 
display file for example #1 

T0011IDX QATTUIM *PNLGRP Online help information referred to by 
the index search object 

T0011DD5 QATTDD5 “FILE Source for physical file for example #3. 

T0011HL2 QATTUIM *PNLGRP Online help for example #2. 

T0011MN2 QATTUIM *MENU Menu for example #2. 

T0011PNI QATTUIM *PNLGRP Panel group for example #3 (contains 
various declarations). 

T0011PN2 QATTUIM *PNLGRP Panel group for example #2. 

T0011PN5 QATTUIM *PNLGRP Panel group for example #3. 

T0011PN6 QATTUIM *PNLGRP Online help for example #3. 

T0011RA5 QATTRPG *PGM List option processing program for 
example #3. 

T0011RE5 QATTRPG *PGM General panel exit program for example 
#3. 

T0011RF5 QATTRPG *PGM Program to process F4 for example #3. 

T0011RF6 QATTRPG *PGM Function key processor for example #3. 

T0011RI6 QATTRPG *PGM RPG PLISTs used by programs for 
example #3. 

T0011RI7 QATTRPG *PGM VARRCD definitions used by programs 
for example #3. 

T0011RL5 QATTRPG *PGM Incomplete list processing exit program 
for example #3. 

T0011RP5 QATTRPG *PGM Main program for example #3. 

T0011RP6 QATTRPG *PGM F4 prompt processor for example #3. 


The other objects are not contained in the QUSRTOOL library but are created 
when you create the example objects into your library: 
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Table 21-3. Objects Created When Creating Example Objects 


Object 
Source Member Type Description 
T0011IDX *SCHIDX Search index object 
T0011MSGFL *MSGF Message file used when creating the 
sample command and display file 


Installing the Example Objects 
To install the displays example, follow the installation instructions in TOO11INF. 
The install programs place all the example objects in a library of your choosing. 


Viewing the Sample Displays, Command, and Online Help Information 


You can view the sample displays, command, and online help information after 
installing the example objects. To view the samples, enter the following com- 
mands: 


¢ To view the sample menu, enter: 
CALL PGM(your-library/TQO11DCL) PARM(MENU) 


The sample menu appears: 


Go To Another List 
Select one of the following: 


. Work with documents in folder 

. Work with documents to be printed 
. Work with folders 

. Work with nontext document data 

. Work with text profiles 


arWNr 


Selection 


F3=Exit F12=Cancel 


— 


Figure 21-1. Sample Menu in QUSRTOOL 


Press the Help key to view the online help information for the display. The 
online help information shown depends on where the cursor is located when 
you press the Help key. 


¢ To view the sample entry display, enter: 
CALL PGM(your-library/TQO11DCL) PARM(ENTRY) 


The sample entry display appears. 
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— 


Type choices, press Enter. 


Place on job queue .... 


Merge Options 


Send completion message... . 


Job description. ..... 
LI DPA 5.8) ee. Soe we 


Adjust/paginate option 


Multiple line report ... 


Collect footnotes 


in merged document ... 


F3=Exit F4=Prompt  F12=Cancel 


Y=Yes, N=No 

Y=Yes, N=No 

Name, F4 for list 
Name, *LIBL 

1=Do not adjust 

2=Line ending only 
3=Line and page ending 
Y=Yes, N=No 


Y=Yes, N=No 


Figure 21-2. Sample Entry Display in QUSRTOOL 


Press the Help key to view the online help information for the display. The 


online help information shown depends on where the cursor is located when 


you press the Help key. 


To view the sample information display, enter: 


CALL PGM(your-library/T0011DCL) 


The sample information display appears: 
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PARM( INFO) 


21-5 


View Document Details Page 1 of 2 
Creation date ..... : 00000000 
DOCUMENT: coe a ee Bess : 000000000000 
Document description . . : 000000000000000000000000000000000000000000000 
Subject: 2.4 oe a ee a t  0000000000000000000000000000000000000000000000000 
00000000000 
Change formats/ 

options ....... . (0) Y=Yes, N=No 

AUtHOYS, <s206 ude ah aes :  00000000000000000000 0000000000000000000 
Keywords ........ t  0000000000000000000000000000000000000000000000000 


000000000000000000000000000000000000000000000000000000000000000000000000000000 
0000000000000000000000000000000000000000000000000000000 


Document class ..... : 0000000000000000 
Print as labels ....3: fe) Y=Yes, N=No 


Press Enter to continue. 


F3=Exit F12=Cancel 


— oe 
f= >) 
View Document Details Page 2 of 2 
PROJEGt. soe a Re ae : 0000000000 
Reference ....... :  0000000000000000000000000000000000000000000000000 
0000000000 
Status: a. ga eas Ge ee a : 00000000000000000000 
Document date ..... : 00000000 
Expiration date ... . : 00000000 
SOME 60. wo sists detpnes, oot antes :  0000000000000000000000000000000000000000000000000 
000000000 
Date action due ... . +: 00000000 
Date action 
completed ...... : 00000000 
Mark for 
offline storage ...: 0 1=Do not mark 
2=Mark and keep 
3=Mark and delete document content 
4=Mark and delete document 
Press Enter to continue. 
F3=Exit F12=Cancel 
Nees aah 


Figure 21-3. Sample Information Display (Two Pages) in QUSRTOOL 


Press the Help key to view the online help information for the display. The 
online help information shown depends on where the cursor is located when 
you press the Help key. 


¢ To view the sample list display, enter: 
CALL PGM(your-library/TQO11DCL) PARM(LIST) 


The sample list display appears: 
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Work with Documents in Folders 


Folder 
Position to. ..... Starting character(s) 


Type options (and Document), press Enter. 


1=Create 2=Revise 3=Copy 4=Delete 5=View 
6=Print 7=Rename 8=Details 9=Print options 10=Send 
11=Spell 12=File remote 13=Paginate 14=Authority 

Opt Document Document Description Revised Type 


000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
Bottom 

F3=Exit F4=Folder list F5=Refresh F6=Print list 

F9=Goto Fl0=Search for document F12=Cancel 


— — 


Figure 21-4. Sample List Display in QUSRTOOL 


Press the Help key to view the online help information for the display. The 
online help information shown depends on where the cursor is located when 
you press the Help key. 


e To view the index search function, do the following: 


1. Type the command to show any of the displays shown in Figure 21-1 on 
page 21-4, Figure 21-2 on page 21-5, Figure 21-3 on page 21-6, or 
Figure 21-4. 

. Press the Help key to show the help for the display. 

. Press F11 to use the index search function. 

. Press F5 to show all the topics available in index search. 

. You can choose to view any topic shown in the list. The second topic in 
the list contains a hypertext link. The fourth topic in the list uses the same 
panel group as the help for the command. 


of OW P 


¢ To view the sample command, enter T0Q11CMD: 


Press the Help key to view the online help information for the command. The 
online help information shown depends on where the cursor is located when 
you press the Help key. 


Copying the Source for the Example Objects for Your Own Use 
You can tailor the example objects for your own use after you copy the source from 
the QUSRTOOL source file. There are basically two different ways that you can 
copy the source from the QUSRTOOL source file: 


e You can copy one member at a time using the browse/copy services function of 
SEU. 


¢ You can copy all members from a QUSRTOOL source file (for example, all CL 
source members contained in QATTCL) at one time using the Copy Source File 
(CPYSRCF) command. 
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Defining Special Functions and Attributes for All Displays 


The following functions and attributes are required for all AS/400-style displays: 


Table 21-4. Required Functions and Attributes of All AS/400-Style Displays 


Function 


Description 


Online help informa- 
tion 


Available from every display using the Help key and a command 
attention (CAnn) key as an alternative Help key. The default for 
the alternative Help key is CA01, which assigns the help function to 
F1 (the CUA designated Help key). 


Blinking cursor 


Blinks as long as the record appears on the display screen. 


Command function 
keys CF03 and 
CF12 


Allows the corresponding function keys (F3 and F12) to be active 
on the display 


Help clearing 


Ensures that only the current help is available. 


The following functions and attributes are optional for all AS/400-style displays: 


Table 21-5. Optional Functions and Attributes of All AS/400-Style Displays 


Function 


Description 


Print key 


Allows the user to print a display 


Page Up and Page 
Down (Roll Up or 
Roll Down) keys 


Allows the user to page the message subfile 


Alternative Page Up 
and Alternative Page 
Down (Alternative 

Roll Up and Alterna- 
tive Roll Down) keys 


Assigns a command function (CFnn) key as an alternative paging 
key (default keys are CFO7 and CFO8, respectively) 


Keyboard locking 


Avoids unlocking the keyboard until the system has finished writing 
the display and is ready for input. 


Designing the Single-Choice Menu Display 


An AS/400 system menu shows a list of choices from which the user can select 
one choice. It always has a title, an instruction, a list of choices, and a labeled field 
for typing the number of the choice selected. Figure 21-5 on page 21-9 shows an 


example of a menu. 
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Title 


io =) 
Go To Another List 
Select one of the following: 
1. Work with documents in folder 
2. Work with documents to be printed 
3. Work with folders 
4. Work with nontext document data 
5. Work with text profiles 
Selection 
F3=Exit F12=Cancel 
ane a 


Figure 21-5. Sample Application Menu 


Before you continue designing this display, define the required and, if desired, 
optional functions and attributes found in “Defining Special Functions and Attributes 
for All Displays” on page 21-8. 


For information about viewing this sample display or copying the source for your 
own use, see “Using the Displays Example in the QUSRTOOL Library” on 
page 21-1. 


The title should be centered on line 1, in mixed case, and displayed in high inten- 


sity. 


Instruction Line 
The guidelines for an instruction line are as follows: 


Menu Options 


e The instruction line is located on line 3 and begins in position 2. It tells the 
user to choose between the options listed on the display. 


e The instruction line format for a menu is: 


Select one of the following: 


Note that the instruction line ends in a colon. 


e All instruction lines on system displays are specified as blue on color displays. 


e Leave line 4 blank and begin the menu options on line 5. 


The guidelines for menu options are as follows: 


e Begin the options following one blank line after the instruction line. 
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e List the options (one per line) starting in position 7 for options 1 through 9 and 
position 6 for options 10 and above. The option number is followed by a period 
and is not highlighted. 


e Limit the number of options to a maximum of 10 wherever possible. 


¢ Options are single-spaced and in numeric order. A gap in the numeric 
sequence is indicated by one blank line, regardless of how many numbered 
options are missing. 


¢ Capitalize the first letter of the first word of the option text; the remaining words 
should be capitalized as appropriate for a sentence. 


e There is no punctuation at the end of each line of the option text. 
¢ If Sign-off is an option on a menu, it should have option number 90. 


e Existing option numbers should not change when new options are added. 


Menu Selection Entry Field 
The guidelines for the menu selection entry field are as follows: 


e The length of a menu selection entry field is one position for option numbers 1 
through 9, and two positions for option numbers 10 or greater (up to 99). 


e¢ The menu selection entry field is located in a fixed position relative to the func- 
tion key area. It begins in position 7 on the second line above the top (or only) 
line of the function key area. 


e The selection prompt is on the line above the menu selection entry field and 
begins in position 2. 

e The text of the selection prompt is: 
Selection 


e The line immediately above the top line of the function key area is blank. 


Function Keys 


Guidelines for defining the function key area are available in “Defining the Function 
Key Area for All Displays” on page 21-33. 


Online Help Information 


Online help information for this sample display using the user interface manager 
(UIM) is available in QUSRTOOL. For information on how to use the source in 
QUSRTOOL, see “Using the Displays Example in the QUSRTOOL Library” on 
page 21-1. 


Guidelines for defining the online help information are available in “Help for the 
Menu Display” on page 21-44. 


General Menu Display Operation 
Following is a summary of what happens when the user presses the Enter key with 
or without making any entries on the menu: 


e If there is no entry in the selection entry field, the menu remains on the display 
(no-operation instruction) and an informational message is displayed, if the key- 
board is not locked. For example: 


Enter option number or command. Press Help for details. 
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e If the value entered was not a valid menu option, a message such as: 
Value entered is not a valid menu selection 
should be issued. 


e If there is an entry that is determined to be a valid option, the requested action 
is processed. 


Designing the Entry Display 


Title 


Entry displays let users type in entry field, and are typically used to provide the 
system parameters and options associated with an action request. Figure 21-6 
shows an example of an entry display. 


Merge Options 


Type choices, press Enter. 


Place on job queue ...... _ Y=Yes, N=No 

Send completion message... .  _ Y=Yes, N=No 

Job description. ....... Name, F4 for list 
Le DMARY ss. aes a) Ber BP Soa Name, *LIBL 

Adjust/paginate option .... 1=Do not adjust 


2=Line ending only 
3=Line and page ending 


Multiple line report ..... 7 Y=Yes, N=No 
Collect footnotes 
in merged document ..... Y=Yes, N=No 


F3=Exit F4=Prompt  F12=Cancel 


— — 


Figure 21-6. Sample Entry Display 


Before you continue designing this display, define the required and, if desired, 
optional functions and attributes found in “Defining Special Functions and Attributes 
for All Displays” on page 21-8. 


For information about viewing this sample display or copying the source for your 


own use, see “Using the Displays Example in the QUSRTOOL Library” on 
page 21-1. 


The title should be centered on line 1, in mixed case, and displayed in high inten- 
sity. 
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Instruction Line 


The guidelines for an instruction line are as follows: 


Prompt Area 


The first character of each instruction line begins in position 2. 


The instruction line for an entry display is a mandatory field in mixed case char- 
acters. The format is one of the following, depending on what is to be entered: 


Type choices, press the Enter key. 
Type changes, press the Enter key. 
Type information, press the Enter key. 


The top instruction line for an entry display ends in a period. 
All instruction lines on system displays are specified as blue on color displays. 


Although a single instruction (one sentence) is recommended, two instructions 
are allowed. Each instruction should fit on a single line with the first character 
of each line beginning in position 2. There is no blank line between the 
instructions. For example, 


Type choices, press Enter. 
Press F16 to send. 


A single instruction can have a maximum length of two lines. The line that is 
carried over is indented two spaces (begins in position 4). 


Type information to define the............... 
of the distribution list, press Enter. 


In general, the columns containing the field prompts and entry fields should be on 
the left half of the display, and the column containing the list of possible choices 
should be on the right half of the display. If all the prompts for a request cannot be 
shown in the prompt area of a single display, make paging of the prompt area pos- 
sible. 


Field Prompts 
The guidelines for field prompts are as follows: 


Field prompts are in normal sentence capitalization and are located to the left 
of the field they identify. 


The first letter of the first word of the prompt should be uppercase; the 
remaining text should be lowercase, unless grammatically incorrect to do so. 


There is no punctuation at the end of the prompt. 


A series of periods (dots) is used to connect the field prompt and the input 
field. 


Dots are spaced every other character. The farthest right dot is in the last 
position within the column width specified for the field prompt, and the dots are 
placed every other position back to the prompt text. There must be three blank 
spaces between the farthest right dot and the input field the prompt identifies. 


The closest dot to the prompt text is two or three positions after the prompt 
(minimum of one blank between prompt text and dot). 


For input fields, there should be room for two or more dots; otherwise dots 
should not be shown. 
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Prompt... (room for at least 2 dots) 
Long prompt (no room for 2 dots) 


Indentation of field prompts and their corresponding input fields is allowed to 
show a level of hierarchy. 


The field prompt column is separated from the column containing the input field 
by 3 character positions (blanks). 


When two or more lines of field prompts are presented, the starting positions of 
the prompts, the dots, and the input fields are aligned. 


Field prompts on entry displays are preceded by an instruction line beginning in 
position 2. The field prompts start in position 4. 


For example: 


Type changes, press Enter. 
Customer name. ........ 
Customer address ....... 
Telephone number ....... 


The instruction line is separated from the first field prompt by one blank line. 


If field prompt text carries over to a second line, it is indented an additional two 
spaces. The input field is after the last line. 


Record format 
OF TUNE Le oe ee 


The use of leader dots with an unformatted (continuous) entry field that carries 
over to multiple lines is the same as with standard formatting. If the field 
carries over to another line, however, it must extend to position 80 and carry 
over to position 1 on the following line. 


Entry fields formatted on a line-by-line basis should occupy individual lines 
beginning with the line following the prompt. The entry fields should be 
indented two positions from the beginning of the prompt. 


The prompt is not followed by leader dots. Never use leader dots unless the 
field being identified is on the same line. 


Memo 


When a single piece of data to be entered has multiple parts, the parts can be 
put on one line if they are understood by the user and considered one piece of 
data. 

Social security number 
Row/column .......... 
A From/To date in a field prompt should be formatted as two fields on one line 
as follows: 

Date filed ........ From _/ / To _/ _/_~ MM/DD/YY 
Document date. ...... From _/ / To _/ _/_~ MM/DD/YY 


Any indication of the type of value (for example, Name), range of value (for 
example, 1 to 99), or specific value (for example, Y=Yes, N=No) should not 
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appear with the field prompt, but should be shown only in the possible choices 
area. 


e For a qualified name hierarchy, indent both the prompt text and the entry field 
by two positions. 


e Indent prompts under a group heading by two positions. A group heading has 
no corresponding input field. The group heading should be followed by a 
colon. It can extend to more than one line, but only one level of indent is 
allowed. 


¢ Do not show an entry field if the value on the display is not meaningful. If entry 
fields are conditionally meaningful, place conditionally valid prompts on a 
display separate from the prompt they are dependent on. 


As an alternative, the prompt can be indented under a group heading that 
defines the conditions. For example: 


Place on job queue. ........ _ Y=Yes, N=No 
For choice Y=Yes: 
Send completion message .... _ Y=Yes, N=No 


Entry Fields: A required entry field requires the user to type a value. Such a field 
cannot be supported by a default. An optional entry field does not require the user 
to type a value. The program can always get a value for an optional entry field by 

defining a default. 


Entry fields take two forms. The first form requests a user-supplied value, like a 
name, descriptive text, or address. Frequently, these fields can accept a value 
from a list of values of variable length and contents. When such a list of valid 
choices exists, F4 should be supported to allow the user to request the list and 
simply choose from it. 


PVC enya Bowl ee Sa Name, F4 for list 


The second type of entry field supports a selection from a fixed set of choices. CUA 
calls this a Selection field. If only one choice can be selected, the choices should 
be numbered. For example: 


Type style. .... 1. 15Prestige elite (12 pitch) 
2=Courier (10 pitch) 
3=Essay standard 


The only exceptions to numbering the choices are when the answers are Yes or No 
and when the choice value has significance to the user by itself. 


If the list of values is longer than five lines, F4 should be supported. 


When the prompt requires a Yes or No response, Y and N should be valid entries. 
For example: 


Duplex ....... Y  Y=Yes, N=No 
When a display first appears, the cursor should be positioned on the first entry field 


that the user will type into. This is usually the first field unless a field specified on 
an earlier display is carried over to this display. 


On some entry displays it is desirable to indicate previous user entries in an entry 


field. For example, if a user typed some command values prior to requesting 
prompting, those user-supplied values would be flagged on the prompt. 
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The greater than symbol ( > ) is used as the indication. In the entry display format, 
there are three blank spaces between the last leader dot and the beginning of the 
input field. The > is placed in the middle space of those three blank spaces. 


Rules for Entry Fields: The following rules apply to the entry fields themselves: 


Required fields cannot have a default. A subvalue of a required specification 
can have a default. For example, a file name parameter is required. No 
default file name is defined but a default library qualification of the file name 
can be provided. 


Required entry fields must be displayed in high intensity. The field prompt and 
possible choices information are in normal intensity. If a value is entered in 
error the value should be shown again in reverse image and underlined. 


Optional entry fields should be normal intensity. 


Wherever possible, optional entry fields should have a defined and displayed 
default value. 


Starting positions for entry fields must be left-justified and aligned (unless there 
are hierarchical fields). 


If defined, default values should appear in the input fields. Values shown in 
fields are left-justified, including numbers that are displayed as character values 
(see Figure 21-6 on page 21-11). When values shown in fields are specified 
as numeric, they are right-justified. 


User-supplied values typed in the entry fields override the default values. 


Use the underline attribute to indicate the length of the entry field. The indi- 
cated length should be the same as the maximum number of characters that 
can be entered. 


The entry field can extend into the possible choices information and even carry 
over into the field prompt area on subsequent lines if needed. If an unfor- 
matted, or continuous, field carries over to another line, it must extend to posi- 
tion 80 and carry over to position 1 on the following line. For example: 


Message text ...... 


If a list of possible choices is appropriate for an extended length input field (see 


“Descriptive Text Area (Possible Choices Information)” on page 21-16), the 
choices may be shown after the input field or accessed through F4. 


Echoed errors (incorrect values in input fields) are displayed again in reverse 
image. The keyboard should be unlocked so that the user can correct the error 
without having to press Error Reset before making the correction. The cursor 
should be positioned at the first field in error. 


Note: If reverse image is used in a highlighted input field (for example, a 
required field), the highlight attribute should be turned off (changed to 
normal intensity) to avoid a no display situation with 5250 display 
stations. 


If a field supports F4 for a list of choices, F4 must remain available if an error is 
made in the field. This is important in helping the user correct the error. 


If the entry display can be paged and the first error is on the currently displayed 
fields, show the display as is without special positioning. If the first error is not 
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on the currently displayed fields, position the first error at the top of the area 
that can be paged. 


Descriptive Text Area (Possible Choices Information): Possible Choices infor- 
mation should be shown in the description area to the right of entry fields for which 
only a predefined set of values or a limited range of values is allowed . If the 
number of values is too great to be shown, or if the values are dynamic, as in a list 
of document names, F4 should be supported. The phrase F4 for list must appear 
as Possible Choices information for that field. (If F4 is supported for all fields on 
the display, F4 for list does not have to appear for each field.) A description of the 
values should also be provided in the Help information supporting the entry field. 


The following rules apply to Possible Choices information: 


e Information for all entry fields on a display should have the same starting posi- 
tion. 


e¢ Choices are separated by one comma and one blank if shown in a horizontal 
character string. 


Y=Yes, N=No 
QDKT, QTAPE1, QTAPE2, *SAVF 
Name, *ALL 


Choices are aligned on the left and on separate lines if shown vertically. No 
comma or other punctuation is shown at the end of any line. 


Y=Yes 

N=No 

1=Prestige elite (12 pitch) 
2=Courier (10 pitch) 

3=Essay standard (proportional) 
4=Essay bold (proportional) 


¢ Capitalize the first word on either side of the equal sign, regardless of whether 
it is the first value, last value, or only value. For example: 


1-255, Blank=Entire instruction 
Blank=Entire instruction, *NONE=None of instruction 


¢ Specific values that can be typed are shown in uppercase. 
PV OS2 oe lt Gat es os Name, *NONE 
¢ Yes and No should be specified by Y=Yes, N=No. 
e Use 'generic*' to indicate that generic names must be followed by an asterisk. 
For example: 
PIVES! oo a es hice oe Name, generic* 
e Identify key numeric ranges. For example: 
Q-99 


If the range is not important, do not include it. For example, if there is no limit 
to the value, do not show anything. 


e lf a numeric value is being prompted and the value must be in specific units, 
identify the type of units. For example: 


Time in seconds 


e In aseries of possible choices without space to show all the values, show the 
most useful beginning with the default and ending with an ellipsis. 


21-16 Application Display Programming V4R1 


Function Keys 


Show a word in quotation marks only when the value being prompted needs to 
be in quotation marks. 


Guidelines for defining the function key area are available in “Defining the Function 
Key Area for All Displays” on page 21-33. 


Online Help Information 
Online help information for this sample display using the user interface manager 
(UIM) is available in QUSRTOOL. For information on how to use the source in 
QUSRTOOL, see “Using the Displays Example in the QUSRTOOL Library” on 
page 21-1. 


Guidelines for defining the online help information are available in “Help for the 
Entry Display” on page 21-46. 


General Entry Display Operation 


The guidelines for entry display operations are as follows: 


If a user blanks out a field that has a default, return the default to the field 
when you show the display again after other checking is completed. Do not 
issue an error message. The function of the display is not performed so the 
user can accept or change the returned default. 


If a user blanks out an optional field that does not have a default, leave the 
field blank. Do not issue an error message. Processing can occur as appro- 
priate. 


If a user blanks out a required field that has no default, a message such as 


Library name is required 
is displayed. 


The other fields on the display screen are checked for errors when a field is 
blanked out and the Enter key is pressed. In some cases, returning the default 
may cause an error, depending on another field on the display screen. When 
these errors occur, error messages should be displayed. 


In all cases, if required values are not supplied or there is no valid entries, the 
display is shown again with an error message indicating what is needed. Fields 
that have an entry that is not valid or that require an entry are shown in reverse 
image. If all fields have valid entries or defaults, the display is processed and 
the dialog proceeds to the next logical display defined for the Enter action. 


Designing the Information Display 


Information displays show protected information. Figure 21-7 on page 21-18 
shows a two-part information display. This example shows a series of output fields 
that are identified or labeled by field prompts. 
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View Document Details Page 1 of 2 
Creation date ..... : 00000000 
DOCUMENT: coe a ee Bess : 000000000000 
Document description . . : 000000000000000000000000000000000000000000000 
Subject: 2.4 oe a ee a t  0000000000000000000000000000000000000000000000000 
00000000000 
Change formats/ 

options ....... . (0) Y=Yes, N=No 

AUtHOYS, <s206 ude ah aes :  00000000000000000000 0000000000000000000 
Keywords ........ t  0000000000000000000000000000000000000000000000000 


000000000000000000000000000000000000000000000000000000000000000000000000000000 
0000000000000000000000000000000000000000000000000000000 


Document class ..... : 0000000000000000 
Print as labels ....3: fe) Y=Yes, N=No 


Press Enter to continue. 


F3=Exit F12=Cancel 


— oe 
f= >) 
View Document Details Page 2 of 2 
PROJEGt. soe a Re ae : 0000000000 
Reference ....... :  0000000000000000000000000000000000000000000000000 
0000000000 
Status: a. ga eas Ge ee a : 00000000000000000000 
Document date ..... : 00000000 
Expiration date ... . : 00000000 
SOME 60. wo sists detpnes, oot antes :  0000000000000000000000000000000000000000000000000 
000000000 
Date action due ... . +: 00000000 
Date action 
completed ...... : 00000000 
Mark for 
offline storage ...: 0 1=Do not mark 
2=Mark and keep 
3=Mark and delete document content 
4=Mark and delete document 
Press Enter to continue. 
F3=Exit F12=Cancel 
Nee a 


Figure 21-7. Sample Information Display (Two Pages) 


Before you continue designing this display, define the required and, if desired, 
optional functions and attributes found in “Defining Special Functions and Attributes 
for All Displays” on page 21-8. 


For information about viewing this sample display or copying the source for your 


own use, see “Using the Displays Example in the QUSRTOOL Library” on 
page 21-1. 
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Title 


The title should be centered on line 1, in mixed case, and displayed in high inten- 


sity. 


Location Information 
Location information for a multiple-part display is right-aligned on line 1 and is in 
the form: 


Page xx of xx 


Prompt Area 1 


The guidelines for field prompts are as follows: 


Field prompts are in normal sentence capitalization and are located to the left 
of the field they identify. 


Field prompts for output fields are not preceded by an instruction line and begin 
in position 2. 


A series of periods (dots) and a colon are used to connect the field prompt and 
the output field. 


The colon is in the last position within the column width specified for the field 
prompt, and the dots are placed every other position back to the prompt text. 
The closest dot to the prompt text is two or three positions after the prompt 
(minimum of one blank between prompt text and dot). 


The field prompt column is separated from the column containing the output 
field by 3 character positions (blanks). 


When two or more lines of field prompts are presented, the dots and colons on 
each line are aligned vertically. 


Output fields are always preceded by a colon, and have no underline attributes 
marking the field length. 


If the prompt requires more than one line, indent the second line two positions. 
The output field is after the last line. 


Record format 
Of TIO. saree ahs : 


For output fields, dots should be used if there is room for one or more in addi- 
tion to the colon. The colon is required. There must be one blank space 
before the colon in the output field format. 


Prompt . . . : XXXXXXX (room for more than 1 dot) 
Med prompt . : XXXXXxx (room for 1 dot only) 
Long prompt : XxXXxxx (no room for 1 dot) 


Indentation of field prompts and their corresponding output fields is allowed to 
show a level of hierarchy. 


When two or more lines of field prompts are presented, the starting positions of 
the prompts, the dots and colons, and the output fields are aligned. 


The use of leader dots and the colon with an unformatted (continuous) output 

field that carries over to multiple lines is the same as with standard formatting. 
The second and subsequent lines, in the case of output fields, are indented by 
two positions from the beginning of the prompt text. 
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Prompt Area 2 


Cause... .: XXXXXXXXXXXX XXX XXX XXX KX XK KX KK XX KX KKK XXX KK KX KK XK KX XK XK 
XXXXXXXXXXXXKo AXXXXXXKXXXKXXKKXK XXX KX KKXX KX KK KX XXX KK XXKXKKXXKXKK KX 6 


¢ Output fields formatted on a line-by-line basis should occupy individual lines 
beginning with the line following the prompt. The output fields should be 
indented two positions from the beginning of the prompt. 


The prompt is followed by a colon with no intervening blank. The prompt is not 
followed by leader dots. Never use leader dots unless the field being identified 
is on the same line. 


Buckslip: 
XXXXXXXXXXXXXKXXXKXXXKXKXKXXXXKXKXKXXKXXKXXKXXKKXKXXKKX KK XKKXXKX KK XX KX XK KX 
XXXXXXXXXXXXXXXXKXXXKXKXKXXXXKX XXX XKX KKK XKXXKKXKKXKKX KK X KKK XK X KKK XKX XK KX 
XXXXXXXXXXXXXXXXKXXXKXKXKXXXXKXKXKXXKXXKXXKXXKKXKKXKKXKKX KK XX KX KKK XK X XK KX 
XXXXXXXXXXXXXXXXKXXXKXXXKXXXXKXKXKXXKXXKXXKXXKKXK KX KK XK KX KKK XK X KKK XKX XK KX 


e When the information to be shown has multiple parts, the parts can be put on 
one line if they are understood by the user and considered as one piece of 


data. 
Social security number ...: XXX XX ~~ XXXX 
Row/column .......2.e- : 27 43 


The prompts on the second part of the information display follow the same format 
as those on the first part of the display. 


Instruction Line 


Function Keys 


Multipart information displays use an instruction line that tells the user how to con- 
tinue or end the dialog with the display. For example: 


Press Enter to continue. 


This bottom instruction line is placed one blank line after the last line of information 
or one blank line above the first function key line. 


Guidelines for defining the function key area are available in “Defining the Function 
Key Area for All Displays” on page 21-33. 


Online Help Information 


Online help information for this sample display using the user interface manager 
(UIM) is available in QUSRTOOL. For information on how to use the source in 
QUSRTOOL, see “Using the Displays Example in the QUSRTOOL Library” on 
page 21-1. 


Guidelines for defining the online help information are available in “Help for the 
Information Display” on page 21-47. 
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General Information Display Operation 


This output information has been set up as separate information displays that the 
user progresses through by pressing the Enter key. A paging model can also be 
used. When the Enter key is pressed, the dialog proceeds to the next logical 
display. The instruction Press Enter to continue should be shown on the display. 


Designing the List Display 


List displays show a list of items from which users may select one or more and 
then specify one or more actions to perform on those items. Figure 21-8 is an 
example of a list display with entry fields. This is called a mixed display. A mixed 
display is a display that combines different types of display elements. 


Work with Documents in Folders fq 


Folder ... 
Position to. ..... Starting character(s) 
Type options (and Document), press Enter. 
1=Create 2=Revise 3=Copy 4=Delete 5=View 5 | 
6=Print 7=Rename 8=Details 9=Print options 10=Send 
11=Spell 12=File remote 13=Paginate 14=Authority 
Opt Document a Description Revised Type 6 | 
7 
~_ 000000000000 00000000000000000000000000000000000 00000000 ooo0000000 fy 
_ 000000000000 —00000000000000000000000000000000000 00000000 0000000000 


000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 


ty =6Bottom 
F3=Exit F4=Folder list F5=Refresh F6o=Print list —iy 
F9=Goto Fl0=Search for document F12=Cancel 


Figure 21-8. Sample List Display 


Reference Key Display Element 

Title 

2 | List control field 

Position to field 

4 | Instruction line 

5 | Options line 

6 | Column heading 

Extended action entry area 
8 | List field 

9 | Paging location information 
Function keys 


Before you continue designing this display, define the required and, if desired, 
optional functions and attributes found in “Defining Special Functions and Attributes 
for All Displays” on page 21-8. 


For information about viewing this sample display or copying the source for your 


own use, see “Using the Displays Example in the QUSRTOOL Library” on 
page 21-1. 


Chapter 21. Designing IBM AS/400-Style Displays 21-21 


Title 


The title should be centered on line 1, in mixed case, and displayed in high inten- 


sity. 


Prompt Area 


In Figure 21-8 on page 21-21, the prompt area consists of the list control field and 
the Position to field. 


The guidelines for field prompts are as follows: 


Instruction Line 


Field prompts are in normal sentence capitalization and are located to the left 
of the field they identify. 


A series of periods (dots) is used to connect the field prompt and the input 
field. The farthest right dot is in the last position within the column width speci- 
fied for the field prompt, and the dots are placed every other position back to 
the prompt text. The closest dot to the prompt text is two or three positions 
after the prompt (minimum of one blank between prompt text and dot). 


The field prompt column is separated from the column containing the input or 
output field by 3 character positions (blanks). 


When two or more lines of field prompts are presented, the farthest right dots 
should be vertically aligned if possible. 


Field prompts that are not preceded by an instruction line (on some mixed dis- 
plays) begin in position 2. 


Input fields have underline attributes marking their length. 


The guidelines for the instruction line are as follows: 


The first character of an instruction line begins in position 2. 
There is no blank line between an instruction line and a following options line. 
The top instruction line for a list display ends in a period. 


If the instruction line is preceded by any information, such as an entry field, it 
must be separated from that information by one blank line. 


The instruction line for a standard action list is as follows: 

Type options, press Enter. 

The instruction line for an action list with an extended action entry is as follows: 
Type options (and Xxxx), press Enter. 


where Xxxx identifies the type of item the list contains, such as Dictionary, Doc- 
ument, and so on. 


When an instruction line followed by an options line is used with a list, the 
instruction and option combination is separated from the list column headings 
by one blank line. 


All instruction lines on system displays are specified as blue on color displays. 


21-22 Application Display Programming V4R1 


Options Line 


The guidelines for the options line are as follows: 


The options line begins in position 4. 


Each listed option has its first letter in uppercase and is preceded by a number 
and equal sign with no intervening spaces. A minimum of two spaces must be 
left between listed options. 


Three lines of options is the maximum (it is recommended that the options line 
be held to two lines). When options extend to more than one line, the digits 
are vertically aligned. List displays can have up to three lines of options if pref- 
erable to a switch to the F23=More options function. 


Use full word names for option labels (for example, 5=Display jobs, 8=Save 
library). 


If more options are not shown, put an ellipsis after the last option shown and 
support and show F23=More options to switch a second set of option 
descriptions into the instruction area. 


Use the following standardized list action codes: 


1 Select (used on the display resulting from pressing F4). Selects for return 
of value to entry field where F4 was pressed. Do not use to select an 
action. The other action codes for the actual action should be used. This 
is only used when an object or item in the list is just being chosen. 


1 Create. Used on lists with an extended action entry in the list, reserved 
for Create on all Work with... displays. 


2 Change or Edit. 

3 = Copy or Hold. 

4 Delete or End. 

5 Display or Work with the actual object represented and its content. If it is 
an object with content, display or work with the content. If itis a 
description, display or work with the attributes it describes. 

Print or Release. 

Rename. 

Display attributes or Detail (the secondary display option) Work with ... 
attributes or Detail (the secondary work with). 

9 Run. 


Work with... actions should be assigned to 5 or 8 if they are not needed for 
Display actions. If both are used, 9 or 12 may be used for the work with 
option. 


The option numbers supported for any list display must be listed in order, but 
gaps are allowed in the sequence. 


If the option field is 2 characters (because of the number of options), typing a 
one-digit selection code in either position of the field should be accepted. 
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Column Headings 


The guidelines for column headings are as follows: 
¢ Column headings are required on list displays and must be in mixed case. 


¢ Column headings should be left-justified over the corresponding data if the data 
is character or character and numeric. Column headings over numeric data 
only is right-justified. When the heading is longer than the data, it should be 
centered over the data. 


e The column heading for the option field should be Option. (Option can be 
abbreviated Opt when space is limited.) 


¢ Columns should be separated by no fewer than two spaces and no more than 
seven spaces. 


¢ Column headings can occupy a maximum vertical size of three lines. 


Extended Action Entry Area 


List Fields 


In the extended action entry area, the first line under the column headings is an 
entry area that cannot be paged. The entry area contains an option field and an 
identifier field. The identifier field is an input field with its length indicated by under- 
line attributes and is the same length as the corresponding output fields on those 
lines of the list that can be paged. For example: 


Opt Document Document Description Revised Type 


Both fields have the attributes of entry fields: underline plus reverse image and 
cursor positioning in case of errors. 


The farthest left column in the list area is the Option column. It contains input fields 
(underlined) 1 or 2 characters long, depending on the number of options available. 
One-character entries are accepted in either position for two-character input fields. 


The column to the right of the Option column should contain the information for 
identifying the list item or for sequencing (if the list is ordered). This column usually 
names the item. 


Lists can be described using subfiles (see Chapter 4, “Displaying Groups of 
Records Using Subfiles”). Use of subfiles, however, does not support the descrip- 
tive paging information used by the system interface at the bottom of the area to be 
paged. 


In the sample list display shown in Figure 21-8 on page 21-21, the fields on the 
available list lines are described using five fields on a line and nine lines in each 
field. The program then loads the successive nine-line blocks of data as the user 
pages through the file. 


The fields in the Option column have the attributes of entry fields. The fields in the 
other columns, being defined as input/output (B), have the protect attribute to 
prevent user access. 
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Paging Location Information 
Whenever the user is on any part other than the last part of an area that can be 
paged, the phrase More... appears highlighted (high intensity) in the location infor- 
mation field on the bottom separator line. When the user is on the last display of 
an area that can be paged, More... is replaced by Bottom. 


The location information field is defined as the seven farthest right display positions 
of the bottom separator line. More... and Bottom are right-aligned in this field. 


When multiple areas on a mixed display can be paged, each requires its own 
paging information. Figure 21-9 shows the layout of a display with location infor- 
mation. 


01 Display Title 
02 Top Separator Line 

03 Display Body 

04 

05 ------------ start of paging area - ---------- ---- 
06 

07 

08 

09 

10 

11 

16 

12 

13 


22 Bottom Separator Line More... 
23 Function Key Area 
24 Message Area 


Figure 21-9. Layout of Display with Location Information 


Each allowable constant is conditioned by an indicator. The program must display 
the correct constant, depending on the status of the paging. 


Function Keys 


Guidelines for defining the function key area are available in “Defining the Function 
Key Area for All Displays” on page 21-33. 


Online Help Information 


Online help information for this sample display using the user interface manager 
(UIM) is available in QUSRTOOL. For information on how to use the source on 
QUSRTOOL, see “Using the Displays Example in the QUSRTOOL Library” on 
page 21-1. 


Guidelines for defining the online help information are available in “Help for the 
Information Display” on page 21-47. 
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General List Display Operation 
The processing priority of a mixed list display when the Enter key is pressed is as 
follows: 


e The list control field (folder, dictionary, and so on) at the top of the display 
e The Position to prompt 

e The extended action entry area 

¢ Options within the list proper 


Error diagnosis follows this same sequence. 


On this type of mixed list display, the list control field at the top of the display 
normally contains the name of the object (folder, dictionary, and so on) whose con- 
tents are being displayed. By changing the name, for example to another valid 
folder name, the user is essentially issuing a display command for the contents of 
the newly specified folder. When the user presses the Enter key, the list display 
area is then replaced with a new list display. 


Operating the List Control Field 

The list control field specifies what the list contains. For example, by changing the 
list control field from FOLDER1 to FOLDER2 and pressing the Enter key, the user 
gets a new list that displays the contents of FOLDER2. 


The guidelines for the operation of the list control field are as follows: 


¢ Once a list of items is displayed, changing the name of the list in the list control 
field while selections within the list are pending causes an error message. The 
pending selections are saved and the list control field with the changed name is 
in reverse image. The error message must include the name that was changed 
so the user can change the name back, if desired. 


Blanking out the name simply results in the name being restored when the list 
is displayed again after pending operations are completed. 


e If a list of items from folder A is being displayed and there are no pending 
selections entered in the list, the user may obtain a list of items from folder B 
by changing folder A to folder B in the list control field and pressing the Enter 
key. 


e While a list of items from folder A is being displayed with no pending requests, 
the user may perform a specific function on a particular item in folder B by 
changing folder A to folder B, typing in the selected option number and the 
identifier in the extended action entry area, and then pressing the Enter key. 
After the option is performed, the folder B list is displayed. 


e lf folder A is changed to folder B in the list control field and the Enter key is not 
pressed, and then a page/roll operation is attempted (with or without selections 
pending), the page/roll is not performed, an error message is shown, and the 
list control field is in reverse image. 


Positioning the List 
The guidelines for positioning the list are as follows: 


e The Position to function is used for quick repositioning of the list. 


— If the user specifies the character S as the starting point, the resulting list 
starts with the first S item and includes all items after that as well, not just 
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the items beginning with S. When positioning to S, if the list contains AA, 
BB, SA, SB, the list is positioned to SA. 

— Once the list has been repositioned, the Page Up and Page Down keys 
can still be used to page to any other items in the list. 

— The special values *TOP and *BOT are supported to position the list to the 
beginning or end. 

— If no items are found that begin with the characters entered, the list is posi- 
tioned beginning with the item immediately preceding the requested posi- 
tion. 


e After a Position to function, the item to which the list is positioned should be at 
the top of the list area, the cursor should be on the first option field that follows 
the input-capable field (if one exists), and the Position to field should be 
blanked out. 


e The Position to field is not checked for being a valid syntax name or a direct 
match on a name in the list. Instead, the user is positioned in the list where 
the entered string would fit based on collating sequence rules (the user can 
enter A& to position to where A& is in the collating sequence). 


¢ Position to field entries in the list option column are ignored. If the user types 
characters into this prompt and presses the Enter key while operations are 
pending in the list area of the list, the list is repositioned and the selections are 
saved, just as if a page/roll key had been pressed. 


Positioning to Lowercase Names in a List 

If you support a Position to prompt for your list, and the items in the list have lower- 
case characters, you should follow these rules to let the user position the list to 
those items: 


e lf the input in the Position to field does not begin with double quotation marks 
("), the input should be folded to uppercase and positioned to the name closest 
to that uppercase name. 


e lf the input in the Position to field begins with double quotation marks ("b or 
"b"), the list should be positioned to the name closest to "b. 


If the user types the ending quotation marks ("b"), you must strip them off so 
that list positions to the name beginning with the double quotation marks ("b). 
Otherwise, it will look for "b" in the collating sequence. 


e If double quotation marks are used on a string that has no special or lowercase 
characters that would require quotation marks, they are removed, and the list is 
positioned to the name that is not marked by quotation marks. 


Using the following list, 


Wag 
"bb" 

AAAAA 
BBBBB 


— Position to "b and Position to "b" should both put "bb" at the top of the list. 


— Position to "AAA," Position to "AAA, and Position to AAA should all put 
AAAAA at the top of the list. 
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Changing the List Control Field and Positioning the List 
Options for positioning the list include: 


e If the list control field is changed to a valid value (a new list can be shown), 
and a value is typed in the Position to field, show the new list positioned 
according to the Position to field. 


e If the list control field is changed to a value that is not valid and a value is 
typed in the Position to field: 


— Display the same list 
— Reverse image the list control field and show the message 
— Position to field remains as typed; list is not positioned 


Operating the Extended Action Entry Area 
The guidelines for the operation of the extended action entry area are as follows: 


¢ The cursor is initially positioned on the option field of the extended action entry 
area. The cursor returns to this position after either of the following operations: 


— Position to 
— Any paging operation 


e Figure 21-10 shows the processing priority used by the system when the 
Create function is used with an extended action entry area: 


Are 
other options 
(if any) in 
list 
valid? 


Error. 
Create is not done. 


Does 


e Create field goes to reverse image. 


the item 
e Error message. 
to Spay ie ala e List is not repositioned to existing item. 


Is 
there a 
"Position to" 
value? 


® Create is done. 
® Other options (if any) specified 
in list are performed. 


e List is positioned. 
e No create is done. 
e Other options (if any) are not processed. 


RV3W066-0 


Figure 21-10. Example of Processing Priority with List Display 
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¢ Specifying the Create option on any list line other than the extended action 
entry area results in an error. 


¢ Specifying the Create option creates a single new list item identified by the user 
(using the extended action entry area). If the program requires other user- 
supplied information to create the list item, it must present the user with an 
entry display on which to supply that information. 


e The user can enter any of the other options valid for that list using the 
extended action entry area. The user must identify the list item the action is to 
be performed against by typing the name of that item in the input field on the 
extended action entry area. 


¢ Options entered in the extended action entry area are valid against any item in 
the list proper. The user can perform an option against any item identified in 
the list proper. 


e In the extended action entry area, if an option is entered and an identifier is 
not, an error message should state that no function can be performed unless 
an identifier is specified. There are two exceptions: 


— The identifier is one of the items prompted for on an accompanying entry 
display that is always presented to the user 

— The program supports creating a temporary object (for example, a query) 
that can be named later 


e If an identifier is entered and an option is not, no operation is performed 
against the contents of the identifier field. 


e The identifier field can contain a defaulted value. When list processing is per- 
formed, the option field in the extended action entry area is restored to blanks. 
The identifier field, however, can keep a defaulted value. 


List Operation When Options Are Specified 
The following rules cover the general operation of lists that have options (actions) 
specified against items (objects) in the list. 


List processing should follow these general rules: 


e The sequence of list processing should match the sequence in which the list 
items are presented on the display screen; that is, proceeding from the top line 
to the bottom line (and from left to right if there is more than a single item ona 
line). 


e After processing, the same view of the list that was presented before pro- 
cessing should be shown again (unless an error occurs). 


Specific rules for list operations are as follows: 


e The user can choose the same or different options for more than one list item. 
The choices can be made on any of the item displays that can be paged. 
Options are not processed until the Enter key is pressed (on the list display 
itself or on an entry display that was displayed after the Prompt key was 
pressed). 


e There should not be a limit on the number of options that can be typed on a list 
(except the Select option). 


e If the user does not have the proper authority to perform the operation, display 
such a message on the message line. 
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¢ Operations are performed in the order shown in the list area. 


Note: Some operations supported on list displays (Delete is an example) can 
be grouped together on a separate display when presented for confir- 
mation. Confirmation is given on the group of operations, but then each 
operation is performed in the order shown in the list. 


e When list processing has completed, after having started from a page other 
than the first, the user is returned to the same page of the list, and the list 
position does not change (unless an error occurs). However, if the top entry of 
the page was removed as a result of a delete operation, the list is positioned 
such that the next remaining entry prior to the deleted entry is at the top of the 
list. 


When processing is completed, after being started from the first page, the list is 
positioned with the current top entry in the list, even if entries were added to or 
deleted from the beginning of the list. 


e The page/roll keys are used to move forward and backward through the list. 
Pressing a page/roll key causes a full page roll (all items are replaced). 


e Even if a list allows a user to perform only one operation, the user should be 
allowed to roll even after one item has been chosen, because processing will 
not occur until the Enter key is pressed. 


e When a page/roll key is pressed, any selections made should be saved (the 
operations should not be performed). 


e Lists that can page will not wraparound at the beginning or end of the list. 


¢ lf multiple display operations are being performed, they should be done one at 
a time, with completion of each indicated by the user pressing the Enter key on 
the last display. 


e If the user interrupts list processing before it is finished (for example, by 
pressing F3 or F12 from an interim display), the list is shown with all processed 
options blanked out (in the Option column). All unprocessed options are still 
marked. The option that was being processed when F3 or F12 was pressed 
(the one where the cursor was positioned), is considered processed and, there- 
fore, is unmarked. 


e If no processing errors occur, all operations are completed prior to the list being 
shown again. 


e If a processing error is detected, processing is interrupted at that point to allow 
the user to handle the error. The list can be displayed again with the option 
field corresponding to the error in reverse image and the cursor positioned to 
that field. A separate display may also be presented that allows the user to 
handle the error. The appropriate error message is always presented on the 
message line. When the user has resolved the error condition, list processing 
is started again. 


e If multiple errors are detected, the list is displayed again with all option fields 
corresponding to the errors in reverse image. The cursor is positioned to the 
first field in error. 


If the list display can be paged and the first error is on the currently displayed 
fields, show the display as is without special positioning. If the first error is not 
on the currently displayed fields, position the first error at the top of the area 
that can be paged. 
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e You can elect to have applications either dynamically update the list as the 


operations in the Option column are performed, or wait to display the updated 
list until the user presses F5=Refresh. Each option is described as follows: 


— A dynamic update of the list can be done if the number of entries in the list 
is not large and the update can occur as operations are performed without 
a significant delay. 


— If the number of entries is large and updating the list would result in a 
noticeable delay, the list should be updated only when the user presses 
F5=Refresh. If dynamic updating is not used, the entries that the user has 
operated on (by entering an option next to one or more), and therefore 
changed, should be annotated as to what operation has been performed on 
them. The annotation should be made in a status field to the right of the 
entry. Annotation should only be made by type of operation (for example, 
operations that change the item or its status, such as Delete or Change, 
should be annotated; operations such as Display should not.) No anno- 
tation should be made on an entry where the operation failed. The anno- 
tation should indicate the type of operation performed on the item. Show 
(Ended) if the entry was ended, (Held) if held, (Changed) if changed, or 
(Released) if released. Abbreviations that correspond to the operation per- 
formed, such as Cn1, H1d, Chg, Rls, can be used if needed. 


Cursor Positioning Rules 
Cursor positioning rules are as follows: 


When a list display is initially shown, position the cursor to the option field for 
the first item in the list. Follow this rule even when there are some secondary 
fields (for example Position to) at the top of the display. 


When a list is presented after a position list or a page/roll function, position the 
cursor to the first option field in the list area. After a position list function, the 
item to which the list is to be positioned should be at the top of the list area 
and the cursor should be in the option field for that item. 


When another view of the list is presented, the cursor should remain on the 
entry where it was (unless the cursor was not in the list area originally; then it is 
positioned at the first item in list). 


After selected operations have been performed and the list reappears, the fol- 
lowing rules apply: 


— The user should always return to the same page of the list from which the 
Enter key was pressed. This is the primary rule. 


— Place the cursor by the last item selected. If that item is not on the current 
display, place the cursor by the first item on the current display. 


— lf the list was positioned at the top before the Enter key was pressed, the 
list should stay at the top when processing is complete. For example, if an 
item was added to the beginning of the list, position the list to start with the 
new item. The user expects to see the top of the list if positioned to the 
top. 


— When errors are detected, position the cursor in the first option in error 
(options in error should be in reverse image). The list should be positioned 
again only if the entry that caused the error is not on the current display 
page. 
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Error Condition Rules 
Error condition rules are as follows: 


e¢ When a page/roll key is pressed, option number fields are checked for entries 
that are valid. 


e When an Exit or Refresh function is performed, the entries on the display are 
not processed, and errors are not returned to the user. 


e If errors occur, the option field corresponding to the error is in reverse image, 
the cursor is positioned to that field, and the appropriate error message 
appears on the message line. 


If the list display is can be paged and the first error is on the currently dis- 
played fields, show the display as is without special positioning. If the first error 
is not on the currently displayed fields, position the first error at the top of the 
area that can be paged. 


e If the first error is on the currently displayed fields, show the display as is 
without special positioning. If the first error is not on the currently displayed 
fields, position the first error at the top of the area that can be paged. 


e Each product can have an internal limit for the number of selections that can be 
made from a list at one time. If the user exceeds this limit, display an error 
message. This error message should include these items: 


— The fact that the maximum number of allowed selections has been 
exceeded. 

— The amount by which this maximum number was exceeded (so the user 
knows how many selections to remove). 


When this message is presented, the pending selections should not be in 
reverse image. 


e Issue the following errors if the user attempts to page past the top or bottom of 
an area that can be paged: 


— Top message 
Message Text: Already at top of area. 


Cause: You pressed a key to move backward in an area. However, you 
cannot move in that direction because you are already at the top of that 
area. 


Recovery: If you want to move displayed information backward in another 
area, move the cursor to that area and press either the Page Up key or the 
Roll Down key again. 


— Bottom message 
Message Text: Already at bottom of area. 


Cause: You pressed a key to move forward in an area. However, you 
cannot move in that direction because you are already at the bottom of that 
area. 


Recovery: If you want to move displayed information forward in another 
area, move the cursor to that area and press either the Page Down key or 
the Roll Up key again. 
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List Where Only One Item Can Be Selected 
If more than one item is selected and the Enter key is pressed: 


e List is shown again with all selections still marked 
e All selections are in reverse image 
e Issue the message: Only one selection allowed 


If one or more items are selected and a Roll key is pressed: 


e No message is issued 
e Roll is performed 


List Format in Empty List Situation 
If the user requests a list of items and there are no items available, the rules are as 
follows: 


1. Start the text in column 4 on the second line following the list area column 
headers (leave one blank line). If only one list line is available, place the text 
on the line immediately following the column headers. 


Opt Document Date Text 


..-blank line... 
(No documents in folder) 


2. The attributes of the text should be of normal emphasis and normal color 
(green). 


3. If the Help key is pressed while the cursor is anywhere in the list area, pro- 
cessing should be done as though the list is not empty (online help information 
is available for the columns). 


4. The text should be generic and state that the list is empty, but should not state 
the reason. The text should be in parentheses. 


5. The text should begin with No xxxxxxxx where xxxxxxxx identifies what is not 
displayed. The phrase should not be followed with a period, because it is not a 
full sentence. For example: 


(No objects in library) 


6. If information about why the list is empty is desired, present it in a message on 
the message line. 


Defining the Function Key Area for All Displays 
The guidelines for the function key area are as follows: 


e List active key assignments from left to right in numeric order, beginning at 
position 2. Active F keys cannot be omitted (with the exception of F1) unless 
they are displayed by the More keys function, in another set of keys. Capitalize 
only the first letter of the first word in the function descriptions. 


e Leave three spaces between key assignments unless more are needed for 
alignment. 


e When function keys are displayed on two lines, align the key assignments on 
the left (on F) if possible. 


F3=XXXXXXXXX F4=XXXXX F5=XXXXXXXXXXX F6=XXXXXXXXXXXX 
F7=XXXXXXX F12=XXxXXXXX F13=XxXXXXXX 
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e Display the keys in ascending numeric sequence (gaps in the sequence can 
exist). 


e If one line of a two-line function key area contains a function key description 
that is very long (that is, forces a gap of up to seven blanks), this description 
may span two or more function key descriptions on the other line for the 
purpose of alignment. For example: 


F3=Exit F4=Prompt F9=Retrieve  F12=Cancel 
F13=Information Assistant F16=System main menu 


e If all the active keys cannot be displayed in two lines, support F24=More keys. 
The guidelines for what to display are: 


— Enter, Help, and the Roll or Page keys should not be displayed. 


— Display active function keys in multiple one-line or two-line sets. Use 
F24=More keys to see the next set of function keys in the function key area 
of a display. All sets must reserve the same number of lines, one or two. 


F3=XXXXXXXXX F4=XxXXXX F5=XXXXXXXXXXX FO=XXXXXXXXXXXX 
F7=XXXXXXX F12=Xxxxxxx F24=More keys 


— F8=Exit and F12=Cancel must be shown in the primary set (and only in that 
set). Only F24 is displayed in all sets. 


— Although the function keys should be in numeric sequence in each set, the 
application can determine which keys are in each set. The functions dis- 
played in the primary set should be those that are used the most. 


e Displayed function keys on system displays are specified as blue on color dis- 
plays. 


Optional Command Line and Identifier Field 


You have probably seen other system menus with a slightly different format. 
Figure 21-5 on page 21-9 shows a menu from within an application, and is the 
type of menu you should create. System menus have an additional system identi- 
fier in the upper left corner. This is used as a name in conjunction with the GO 
command. Such names have to be present as object names in system tables. 


The system uses names in this identifier field only on menus accessed by the GO 
command. Using this identifier field on application menus could confuse the user 
because the names would not work with the GO command. A user can access the 
system menus, given the menu identifier. Using the GO command, a user can 
specify a particular menu, by the menu identifier, or, if a particular menu is not 
known, a generic identifier can be used. In this case, the user is shown the Work 
with Menus display and from this list, can specify a menu to run. For more infor- 
mation on how to create display file menus, see Chapter 9, “Creating and 
Accessing Menus Using Display Files” on page 9-1. 


System menus also use a command line as the entry field for menu selection. The 
only command area support DDS provides is to allow you to define an entry field 
(with accompanying field prompt) into which a command could be entered. You 
write all code to support this entry area as a command area, including passing the 
command to the system, handling the Prompt function, handling the Retrieve func- 
tion, and handling help for the command. “Available Command Line Tool” on 

page 21-37 provides information on a command line function available in the 
QUSRTOOL library to assist in putting a command line on an application display. 
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To support commands from within an application, make one or more system dis- 
plays with a command line available or provide a command line on one or more 
application displays. 


Note: If the commands change something the application is dependent on, results 
that cannot be predicted can occur. 


With the AS/400 system you can limit command entry to the system commands 
and application commands you want. Typically, this is the best approach for the 
user. You can limit the user to special commands by specifying *YES for the Limit 
capabilities prompt on the Create User Profile (CRTUSRPRF) display, as in 

Figure 21-11. You can then create commands with the Create Command 
(CRTCMD) command. Specify *YES for the Allow limited users prompt to make 
the command available to limited users as in Figure 21-12 on page 21-36 and 
Figure 21-13 on page 21-36. 


Note: Most commands are shipped with ALWLMTUSR(*NO). See the Limit capa- 
bilities (LMTCPB) prompt on the Create User Profile (CRTUSRPRF) display 
for a list of ALWLMTUSR(*YES) commands. You can change IBM-supplied 
commands with the Change Command (CHGCMD) command. If you 
change an IBM-supplied command you must keep track of your changes in 
a control language (CL) program because the commands are replaced with 
each release. 


(i — 
Create User Profile (CRTUSRPRF) 

Type choices, press Enter. 
User profile. ......... ame 
User password ......... *USRPRF___ ame, *USRPRF, *NONE 
Set password to expired .... *NO_ *NO, *YES 
User class. 4 a eee 6 Ewe *USER__ *USER, *SYSOPR, *PGMR... 
Current library ........ ame, *NONE 
Initial program to call ....  *NONE ame, *NONE 

LET DTARY oe. eo. eves ey ee tees eget ame, *LIBL, *CURLIB 
Initial menu. ......... MAIN ame, *SIGNOFF 

TDL APY: « nase ct a Cte ah y Seve? val Ser st *LIBL ame, *LIBL, *CURLIB 
Limit capabilities ....... *YES *NO, *PARTIAL, *YES 
Text 'description’....... *BLANK 

Bottom 

F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel 
F13=How to use this display F24=More keys 


Figure 21-11. Create User Profile Entry Display 


Chapter 21. Designing IBM AS/400-Style Displays 21-35 


Create Command (CRTCMD) 


Type choices, press Enter. 


COMMANG ei ee dos eae ee 8 Name 

LIDROY | a-55 Yes-scee too eo ene, 9 *CURLIB_ Name, *CURLIB 
Program to process command... Name 

(ES f19) r= ch cae eee *LIBL Name, *LIBL, *CURLIB 
Source€: Tile? a we sea Sx ae QCMDSRC____ Name 

DISA Anrtie cea set to Bee chines *LIBL Name, *LIBL, *CURLIB 
Source member ......... *CMD Name, *CMD 
Text 'description’....... *SRCMBRTXT 


Validity checking program ...  “*NONE Name, *NONE 
LADY ANY. exe eos ee ae es Senge BE Name, *LIBL, *CURLIB 
Mode in which valid ...... *ALL *ALL, *PROD, *DEBUG, *SERVICE 


+ for more values 
More... 
F3=Exit F4=Prompt F5=Refresh  F12=Cancel F13=How to use this display 
F24=More keys 


Figure 21-12. Create Command Display with Additional Parameters Selected 


‘oa a 
Create Command (CRTCMD) 
Type choices, press Enter. 
Where allowed to run. ..... *ALL *ALL, *BATCH, *INTERACT... 
+ for more values 
Allow limited users ...... *YES *NO, *YES 
Maximum positional parameters . *NOMAX 0-75, *NOMAX 
Message file for prompt text . . »*NONE Name, *NONE 
LETDTAP Ys we so ge Wk a ME aR ws *LIBL Name, *LIBL, *CURLIB 
Message file. ......... QCPFMSG_ Name 
LTDA) < -thch net ce us ee ete *LIBL Name, *LIBL, *CURLIB 
Current library ........ *NOCHG Name, *NOCHG, *CRTIDFT 
Product library ........ *NOCHG Name, *NOCHG, *NONE 
AUtTHOVItY™ s eoe. ee ee we *USE Name, *USE, *ALL, *CHANGE... 
Bottom 
F3=Exit F4=Prompt F5=Refresh  F12=Cancel F13=How to use this display 
F24=More keys 


Figure 21-13. Second Display of Additional Parameters 


If your application uses commands, you should define an entry field (with accompa- 
nying field prompt) on the display. To match the AS/400 system, command lines 
should appear as follows: 


Selection or command 
$1 — ie 9 


e The one-line command line begins in position 7 on the line immediately above 
the function key area and ends in position 79 on the same line. 
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e The command line is identified by a command line prompt, beginning in posi- 
tion 2. If the command line is used to enter either the menu selection or a 


command, the text of the prompt is: 


Selection or command 


e The command entry arrow (===>) is in positions 2 through 5 of the first line of 


the command line. 


e The command entry arrow (===>) is normal intensity like the command line. 


Available Command Line Tool 


| General-Use Programming Interface 


The QUSCMDLN program can be used to display a pop-up window that contains a 


command line. The command line can be used to enter system commands. 
QUSCMDLN can be called by any user program. More information about 
QUSCMDLN is available in the System API Reference. 


| End of General-Use Programming Interface 


The QUSRTOOL library on the AS/400 system contains a command line function 
and documentation to assist in putting a command line function on an application 


display (nember CMDLINE, in file QATTINFO, in QUSRTOOL). One way to 
access this function is by using the Work with Members Using PDM 
(WRKMBRPDM) display, shown in Figure 21-14. 


Work with Members Using PDM (WRKMBRPDM) 


Type choices, press Enter. 


PAO te 3" seme Be ioe Sea ee. Rad 28 QUSRTOOL *PRV, name 

LT DPN * or anos bere she eg es QATTINFO__ *PRV, name, *LIBL, *CURLIB 
MeMDET 2. scot. od Ste Cor tae es CMDLINE_—Ss—s *PRV, name, *generic*... 
Member type .......... *ALL *PRV, name, *generic*... 


Bottom 
F3=Exit F4=Prompt F5=Refresh  F12=Cancel F13=How to use this display 
F24=More keys 


— — 


Figure 21-14. Work with Members Using PDM Entry Display 
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Common Key Assignments 


Table 21-6 summarizes common AS/400 function key assignments and indicates 
when each key is used. The keys identified as CUA can be used only for the func- 
tion defined. If the function is not available, the key should not be used for another 


function. 


Non-CUA keys are keys commonly used on the system for a particular function. If 
the function is available on a display, the key assignment given should be used for 
compatibility with system key assignments. If the function is not being used, you 
can use the key assignment for an application-specific function. 


Table 21-6 (Page 7 of 7). Function Key Assignments 


Name 


Usage/Function 


Help 


Set 1/Set 2 


Exit 
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Active on all displays, but not shown on the 
display. F1 is also mapped to the Help func- 
tion but is not displayed in the function key 
area. 


Required when applications need more func- 
tion keys than can be assigned to the 24 
numbered keys. F1=Help, F2=Set n, F3=Exit, 
F9=Retrieve/command, and F12=Cancel are 
required in both sets of function keys. 


Usually active and shown on all displays. F3 
exits the application or a unit of work within 
the application. If the application is exited, 
the user is returned to the display from which 
the application was requested. If a unit of 
work within an application is exited, the user 
is returned to a predefined point within the 
application that serves as a point of focus for 
requesting work (usually a primary menu). 
User input is normally discarded; however, if 
pressing the Exit key could cause loss of data 
and require extensive user effort to retrieve or 
reconstruct, an exit display should be pro- 
vided to give the user the option of saving the 
data before exiting. 


The Exit function must be available on all dis- 
plays except: 


¢ Displays used for confirmation of the 
delete action 

e List display shown as a result of pressing 
F4 

e Exit displays provided to give the user the 
option of saving the data before exiting 


Table 21-6 (Page 2 of 7). Function Key Assignments 


Name Key CUA Usage/Function 


The following describes the use of the Exit 
key for specific display types: 


Menu. If the menu is part of a dialog that 
began with a primary menu or the initial 
menu after sign-on (for example, the 
primary or initial menu is the first menu 
on the current menu stack), returns to this 
primary or initial menu. Pressing the Exit 
key from the primary menu exits the 
current dialog and returns to the display 
from which the dialog was entered. 


List display. Returns to the menu or 
other display from which the list display 
was requested. User input is discarded. 


Entry display. Returns to the menu or 
other display from which the entry display 
(or set of entry displays) was requested. 
User input is discarded. However, an exit 
display can be provided to give the user 
the option of saving the entries or 
changes. 


Information display. Returns to the 
menu or other display from which the 
information display (or set of information 
displays) was requested. 


Any help display. Returns to the display 
from which help was originally requested. 
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Table 21-6 (Page 3 of 7). Function Key Assignments 


Name 


Key 


CUA 


Usage/Function 


Prompt 


21-40 Application Display Programming V4R1 


F4 


Yes 


Should be supported whenever the display 
contains an entry field for which the valid 
entries are known but are not shown on the 
display. F4 provides a list of selectable 
values (usually a list of names) related to the 
field where the cursor is currently positioned. 
When the user selects one or more values 
from the list, those values are used as input 
values for the field. 


If F4 is pressed and the function is not sup- 
ported for the field containing the cursor, the 
user receives an error message. 


If the function is supported for the field con- 
taining the cursor and either a default value 
exists or the user makes an entry in the field, 
the value in the field is kept and the list is dis- 
played. If the user selects a value from the 
list, this value replaces the previous value in 
the field. If the user does not select a value, 
the previous value is kept. 


If the user leaves the field blank and presses 
F4, the list is also displayed for a value to be 
selected. 


When a command is typed on a system 
command line and F4 is pressed, a prompt 
for the command (an entry display with input 
fields for the command parameters) is dis- 
played. 
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Name Key CUA Usage/Function 


Refresh F5 Yes Should be used where the Refresh function is 
appropriate. F5 can start resetting defaults 
on an entry display, or update (refresh) 
system output being displayed. The using 
program determines what is appropriate 
depending on the display type: 


e Menu and help display. Not usually 
used. 


e Entry display. Clears user input and 
shows the display again with the original 
values provided at the time the display 
was first shown. The cursor is reposi- 
tioned at the first logical input field on the 
display. If the entry fields are ona 
display that can be paged, Refresh 
should position the cursor at the begin- 
ning of the list of entry fields. 


e List display. Clears user input and 
updates the display to show the current 
status. Refresh should maintain the 
same position in the list. The list should 
be shown again with the entry that was at 
the top of the list page when F5 was 
pressed still at the top of the list page, 
and with the cursor positioned at the top 
list item. 


e Display with output-only fields (data 
output items). Updates the information 
variable fields to show the current values. 
If the information variable fields are ina 
display that can be paged, Refresh 
should maintain the same position in the 
list of fields. 
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Table 21-6 (Page 5 of 7). Function Key Assignments 


Name Key CUA Usage/Function 


Summary of list positioning rules with the 
Refresh function: 


1. 


The display is shown again with the entry 
that was at the top of the display still at 
the top of the display. 


. If that entry no longer exists, the entry fol- 


lowing it is shown at the top of the 
display. 


. When the first entry in the list was at the 


top, the first entry is shown at the top 
again (even though it may be a new first 
entry). 


. If the entry that was at the top of the 


display no longer exists and there are no 
entries following it, the display is shown 
with the first entry of the entire set of 
values at the top of the display. 


. If the location-determining attributes of the 


entry at the top of the display have 
changed, the list is shown with the entries 
starting where the old entry would have 
been. 


Create F6 No Optional. F6 is used for the Create function 
on a list display that has not converted to the 
combination list with 1=Create. However, 
using a combination list is preferred on the 
AS/400 system. Summary of uses for F6: 


May be requested with the cursor in any 
position. 


Go to separate display in which additional 
object(s) can be defined. 


On completion, show list display from 
which Create request was made again. 


Show created object(s) sorted into the list. 


Requests that were pending at the time 
F6 was pressed should not be processed, 
but should still be pending. 


Note: When a very large number of new 
entries can be added, such as 
with Add Entries to a Distribution 
List, it may be a good application 
decision to not allow an Add or 
Create function until other pending 
requests are completed. In this 
case, a message can be issued 
when F6 is requested and other 
requests are pending. 


Retrieve FQ Yes Required on all panels or pop-up windows 
with a command line. 
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Table 21-6 (Page 6 of 7). Function Key Assignments 


Name 


Key 


CUA 


Usage/Function 


Command 


Cancel 


XXXX Main Menu 


Top of list 


FQ 


F12 


F16 


F17 


Yes 


Yes 


No 


No 


Used to display a pop-up window containing a 
command line. 


Must be active and shown on all displays. 
F12 returns to the previous logical display. It 
provides the basic navigation function of 
backing up one step in the interface, as 
described for the following displays: 


e Menu. Backs up to the previous menu or 
other display from which the menu was 
directly started. Any user input is dis- 
carded. 


e Entry and List displays. Backs up to 
the previous display. User input is dis- 
carded. (If significant data would be lost, 
an exit display should be shown.) 


e Information displays. Backs up to the 
display previously shown. 


Note: If a set of information (including 
input or output fields) can logically 
be presented in a paging format, 
use a display that can be paged 
instead of the Enter and Cancel 
keys for forward and backward 
navigation through the information. 


This function must be available on all dis- 
plays, except when a logical Cancel function 
is precluded by other factors. An example is 
when only the Exit function is appropriate 
because the user must first verify (using an 
exit display) whether data is to be saved or 
not. 


Optional for applications. F16 must be active 
and shown on system menus. It provides a 
direct path to the system or application 
primary menu. A target menu other than the 
system main menu must be explicitly stated. 
This key would normally be used within an 
application to provide a direct path to the 
application main menu. When this key is 
pressed, any user input is discarded. If F3 or 
F12 is pressed on the target menu, the user 
is returned to the display where F16 was 
pressed. 


Optional on displays that can be paged. F17 
pages to the top or beginning (same as *TOP 
in the Position to field). This key should be 
supported when the Position to field is not 
present. 
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Table 21-6 (Page 7 of 7). Function Key Assignments 


Name 


Key 


CUA 


Usage/Function 


Bottom of list 


Left 


Right 


More options 


More keys 


F18 


F19 


F20 


F23 


F24 


No 


Yes 


Yes 


No 


No 


Optional on displays that can be paged. F18 
pages to the bottom or end (same as *BOT in 
the Position to field). This key should be sup- 
ported when the Position to field is not 
present. 


Should be operational on all displays with a 
horizontal area that can be paged. There are 
no common columns of information between 
successive views. 


Should be operational on all displays with a 
horizontal area that can be paged. There are 
no common columns of information between 
successive views. 


Optional. List displays only. Use F23 to 
display the next set of options in the instruc- 
tion area of a list display. Use when the first 
set of options shown in up to three lines is 
not complete. It is recommended that an 
ellipsis be shown after the last option in the 
options area if other options exist that cannot 
be seen until F23 is pressed. The most 
important functions are shown first, and the 
less frequently used options are shown after 
F23 is pressed. 


Optional. Use F24 to see more active func- 
tion keys in the function key area of a display. 
Use when all key descriptions will not fit in 
the two-line function key area. 


Defining Help Information for All Displays 


Help for AS/400 system displays consists of specific information on fields where the 
cursor is positioned, and, when the cursor is positioned anywhere else, general 
information on what the display is for and how the user interacts with it. 


Help on the system also includes a system help index. This section describes the 
type of help support for fields provided by the system for each display type. 


Help for the Menu Display 


The following table and illustration describe the help information for each menu help 


area: 
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Table 21-7. Type of Help for Each Help Area—Menu Display 


Cursor Position 


Help Information 


UIM Tag 


On line containing option 
number and description 


What function each option 
performs 


HELP element of MENUI tag 


In function key area 


Function performed by 
each function key turned 
on for the display 


HELP element of KEYL and 
KEYI tag 


Any other display position 


Beginning of general help 
for display (user can page 
through all help for 
display, which includes 
description of how to use 
the entry line) 


HELP element of PANEL tag 


On command line with no 
entries 


Entry at beginning of 
general help for panel 
(user can page through all 
help for display) 


HELP element of PANEL tag 


On command line with 
option number entered 


What function each option 
performs 


HELP element of MENUI tag 


Menu Panel 
Select one of the following: 


'2. Option 2 description --—~ 


'3. Option 3 description + 


Cursor not on 
any area defined rp -- aes 
with contextual Ses LOP == 
help What Id 
at panel does 
|S Extended 
How to get help Help 
Using command line J 
Cursor in . 
Se ae CE RS AIS s eS p> What option 1 does 
contextual ed, Ter 
idee decane! ae, ec What option 2 does 
help area [$$ $__________ 
fsa te esate te. baa satchel ec eaeee es ee otacens ta b> What option 3 does 
Contextual 
—_______| { Help 
P| What option n does 
> Function keys 
=== bottom === 


From contextual help, 


user can press F2 to go 
to extended help. 


RV2W027-4 


The following table gives the DDS considerations for help on menu displays: 


Table 21-8. DDS Considerations—Help on Menu Displays 


Item Help Area 


Area Covered 


Each menu option 


From position 1 to the farthest right display position on the 
line containing the option number and the option text 


Function key area 


From position 1 on the first line of the function key 
descriptions to the farthest right display position on the last 
line of the function key descriptions 
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The remainder of the display is defined as the general help area. 


Help for the Entry Display 


The following table and illustration describe the help information for each entry 


display help area: 


Table 21-9. Type of Help for Each Help Area—Entry Display 


Cursor Position 


Help Information UIM Tag 


On input field or descriptive 
lines associated with input 
fields (data entry item) 


In function key area 


Use of each possible entry HELP element of DATAI tag 
in input field 


Function performed by HELP element of KEYL tag 
each function key turned 
on for the display 


Any other display position 


Beginning of general help HELP element of PANEL tag 
for display (user can page 
through all help for 
display) 


Cursor not on 


any area defined 
with contextual ———B® === top === 
help 
What panel does Extended 
Entry Panel Help 
Item Choice Position Choices How to get help 
EF FY a LL iactcsiaeee p| Help for aaaa 
| aie er Cra lea ea — eS contextual aad ranted 
CDI ee es cetera een erties Mee a et al pm! Help for bbbb 
feacseasseses Tssses- help area er 
te CCCC ree We ee eee Mee ee eared p! Help for cccc 
Contextual 
—___*_____| | Help 
se oh or hee ead >| Help for nnnn 
J} : 
aeigcheetevteredhaetasecl >| Function keys 
=== bottom === 
From contextual help, 
user can press F2 to 
go to extended help. 
RV2W026-6 


Figure 21-15. Help Areas for Entry Displays 


The following table gives the 


DDS considerations for help on menu displays: 


Table 21-10. DDS Considerations—Help on Entry Displays 


Item Help Area 


Area Covered 


Each item 


From position 1 on the first line of the item text to the far- 
thest right display position on the last line of either (1) the 
input field(s) or (2) the possible choices text, whichever 
occupies the most lines (see Figure 21-15). 


Function key area 


From position 1 on the first line of the function key 
descriptions to the farthest right display position on the last 
line of the function key descriptions 


The remainder of the display 
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is defined as the general help area. 


Help for the Information Display 


The following table and illustration describe the help information for each informa- 


tion display help area: 


Table 21-11. Type of Help for Each Help Area—Information Display 


Cursor Position 


Help Information 


In output field or descriptive 
lines associated with output 
field. 


Meaning of output field. (A data output field is an area on 
a display consisting of descriptive text and an associated 
output field into which variable data is written at display 
time.) 


In function key area 


Function performed by each function key turned on for the 
display 


Any other display position 


Beginning of general help for display (user can page 
through all help for display) 


Cursor not 
on any 
area defined 
with 
contextual ol oe ee it eee 
help oR 
. What panel does Extended 
Information Panel Help 
Item Choice Position Choices How to get help 
Os a gre, ye Cursor in 
| aaaa eer TT i Release eae > Help for aaaa 
Heep stefan a tad gp ier : contextual 
' bbbb SSO ae EA aca A a een tact on et oe eaten pm} Help for bbbb 
poses Ss ees se Sr Ge SS ; help area 
; CCCC Sh) 28 i nee rece eae ee eee ee p| Help for cccc 
pleas Samueie au ekse Contextual 
Tag 0 10 8 ecm 72 27 Re aaa Help 
[oe a sie , Help for nnnn 
| F2=xXxx F3=xxx Fn>0x pee ke 
ee 2  Suisecndece ele dsick Function keys 
=== bottom === 
From contextual help, 
user can press F2 to 
go to extended help. 
RV2W043-5 


Figure 21-16. Help Areas for Information Displays 


The following table gives the 


DDS considerations for help on information displays: 


Table 21-12. DDS Considerations—Help on Information Displays 


Item Help Area 


Area Covered 


Data output items 


From position 1 to the farthest right display position on the 
line (see Figure 21-16) 


Function key area 


From position 1 on the first line of the function key 
descriptions to the farthest right display position on the last 
line of the function key descriptions 


The remainder of the display 


is defined as the general help area. 
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Help for the List Display 
The following table and illustration describe the help infor 
help area: 


mation for each list display 


Table 21-13. Type of Help for Each Help Area—List Display 


Cursor Position Help Information UIM Tag 

In input field or descriptive Use of each possible entry HELP element of LISTCOL 
lines associated with input in input field tag 

fields 

In specific column Meaning and use of HELP element of LISTCOL 


column. This includes 
how to use that entry field 
(for example, creating a 
list entry or performing an 
action against a list entry 
without paging to it) for the 
column containing the 
extended action entry. 


tag 


In function key area Function performed by 
each function key turned 
on for the display 


HELP element of KEYL tag 


Any other display position Beginning of general help 
for display (user can page 
through all help for 


HELP element of PANEL tag 


display) 
List Panel 
Postion cursor enter choices 
1=0x 250K 3=000« 4500 
| 0! (AAA: ' BBB: (CCG | NNN 
PK OK OK foo OOK | 
: ra 1 vt 1 SG ' Cursor not on 
i i! ese 200 ca rOOK any area defined \ 
! Vet it i H f i with contextual ———P === top === 
ice hal ‘| i. ty help Extended 
1 i : ; 1 How to use panel Help 
i How to get help ) 
F250x | F3=0K . FOSQXK 
Option column and 
Insecta esl serare chilies eente abcd ate Shcaeae uceeenece ss sucre 8. os ice escecnse chan sseeade a noseuecnseiod p| text for all option 
Cursorin list actions 
Deas tg Secerge Wg eran ee ee nen, Seog Negi ye ee awa ee > Column AAA 
contextual 
ee bateasd ane asset es tubes PSeuest ess S tvs Oa Cees ies as Cond > Column BBB 
help area ee 
ee eee pec tee beac acne tntenenenenennecniy p> Column CCC Contextual 
Help 
iioekngangasHnceengsiba-rncitnas asin ceeessiaaeinceecsaianiced > Column NNN 
Ieewe ches toes eae thoes ctee ences >| Function keys 
=== bottom === 
From contextual help, 
user can press F2 to 
go to extended help. 
RV2W025-3 


Figure 21-17. Help Areas for List Displays 
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The following table gives the DDS considerations for help on list displays: 


Table 21-14. DDS Considerations—Help on List Displays 


Item Help Area Area Covered 


Each column From the farthest left position on the first line of the column 
heading to the farthest right position on the last line of 
column data. The farthest left position is defined as the far- 
thest left character position of either the longest heading 
line or the data column, whichever is wider. The farthest 
right position is defined as the farthest right character posi- 
tion of either the longest heading line or the data column, 
whichever is wider. (See Figure 21-17 on page 21-48). 


Function key area From position 1 on the first line of the function key 
descriptions to the farthest right display position on the last 
line of the function key descriptions 


The remainder of the display is defined as the general help area. 


Defining and Presenting Messages 


For compatibility with the system, an application should present an error message 
any time a user types a selection or actual value that is not allowed. The message 
itself should provide as much information as possible to allow users to continue 
processing. On the system, messages appear on the bottom line of the display. 


Messages should be supported by help information that gives an expanded 
description of the error (if necessary) and a remedy to the problem. In general, the 
help information should state what happened and, if possible, what to do if an 
action is required. The highest priority should be given to a statement of action 
required. 


The user can request help for the message being displayed by moving the cursor 
to the message line and pressing the Help key. Message help is presented on a 
separate display and can extend to more than one display if needed. 


The DDS keyword ERRMSG is easy to use, but locks the keyboard and lets the 
user see only one message at atime. This option is acceptable if there are only a 
few messages. However, to keep the user's interaction with the message easy, the 
goals are to: 


e¢ Not make the user unlock the keyboard to respond to the message 
e Provide a formatted display that can be paged for additional message informa- 
tion 


To accomplish this, you should use a subfile containing messages from a program 
message queue (SFLMSGKEY, SFLMSGRCD, and SFLPGMQ keywords) rather 
than use the ERRMSG, ERRMSGID, SFLMSGID, and SFLMSG keywords. 


To provide messages that tell the user what is correct, not simply that an entry is 
not valid, validity checking in your program is recommended over using the 
CHECK, RANGE, VALUES, and COMP keywords in DDS. When these keywords 
are used, a message tells the user that what is entered is not valid, but no explana- 
tion or indication of what is valid is given. 


Chapter 21. Designing IBM AS/400-Style Displays 21-49 


Message presentation on the AS/400 system adheres as closely as possible to the 
following rules: 


¢ Detected input errors result in an error message and the function is not per- 
formed. 


e Error messages are shown on the display where the values that are not valid or 
options were entered. The error message does not appear on a separate 
display started by the data entered and the Enter action. 


e When errors are detected on data entered on a display, the display is shown 
again with: 


— The first value(s) in error visible. In the case of a display that cannot be 
paged, the display is shown again with the erroneous values still in the 
fields where they were entered. For the display that can be paged where 
the user only entered values on one display page of values, the display is 
shown again as it appeared when the Enter key was pressed. For the 
display that can be paged where the user has paged and entered values 
on multiple pages, the display is shown again with the first page of values 
that contains an error. 

— The erroneous values are shown in reverse image (if the display station 
supports this). 


Note: If reverse image is used in a highlighted input field, the highlight 
attribute should be turned off (changed to normal intensity) to avoid 
a no display situation with 5250 display stations. 


— The cursor is positioned on the first field with a value in error. 
— The keyboard is not locked. 


e When multiple errors are detected on data entered on a display: 


— Error messages for all errors on the display can be viewed, one at a time, 
on the message line using the roll/page key. 

— If multiple messages are waiting, the last three positions of the message 
line contain "b+b" (b indicates blank) in high intensity to indicate additional 
messages are present. The roll/page keys allow viewing the other mes- 
sages. To page through the messages, the user moves the cursor to the 
message line and presses the appropriate roll/page key. 

— When multiple messages are presented, the messages are in the same 
order as the values in error appear on the display. 

— When the user takes the appropriate corrective action (pressing a key, for 
example), the error message is removed. Only messages for errors that 
have not been corrected are present on the message line or waiting to be 
viewed. 


e lf a user requests help for an item other than the message (the cursor is not on 
the message line when the user presses the Help key), the message remains 
on the display when the user returns from the Help displays. 


Designing Common User Access (CUA) Entry Level Models 


CUA has defined the entry model to guide the programmer of an existing simple, 
transaction-oriented application in redesigning the user interface of that application 
to use some of the standard interface components defined by CUA. The key differ- 
ence between entry and the other CUA models is that entry is action oriented and 
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follows an action-object process sequence. Other CUA models have an object- 
action orientation. 


The CUA entry model closely resembles the existing AS/400 interface. The user is 
typically asked to select an action or task from a menu or list and then indicate the 
object to which that action applies. 


Entry Dialog Actions 


Certain CUA entry dialog actions must be shown in the function key area when 
they are available on the display area. Table 21-15 summarizes CUA entry dialog 
actions indicating the function key assignments and when each key is used. If the 
function is not available, the key should not be used for another function. 


Table 21-15 (Page 1 of 2). CUA Entry Dialog Actions 


Function 


Key 


Usage Requirements 


Enter 


Enter 


Active on all displays, but not shown in function key area 


Help 


F1, Help 


Help must be active on all displays, but is not shown on 
the display. F1 must also be mapped to the Help function. 
F1 is not shown in the function key area. 


CUA screens should have F1 turned on for help; 
however, DDS also allows the Help key to be assigned to 
this function. 


Exit 


F3 


Must be active and shown on all displays except: 


¢ Confirmation displays. 

e List display that appear as a result of the user 
pressing F4. 

e Exit displays that result from the user pressing 
F3=Exit where the decision is made as to save or not. 

e Pop-up windows 


Prompt 


F4 


Must be supported whenever the display contains an 
entry field for which the valid entries are known but 
cannot be shown in the possible choice description area. 
Required on any display with a command line. 


Refresh 


F5 


Required on action list displays (except selection lists) 
and strongly recommended on other list displays. Should 
be used on other displays where the refresh function is 
appropriate. 


Backward 


Page Up, 


Must be operational on all displays with an area that can 
be paged. Not shown in function key area. Page up 
shows the previous page of data. 


CUA displays should have Page up turned on for paging; 
however, DDS also allows F7 to be assigned to this func- 
tion. 


Forward 


Page Down, 
F8 


Must be operational on all displays with an area that can 
be paged. Not shown in function key area. Page down 
shows the next page of data. 


CUA displays should have the Page Down key turned on 
for paging; however, DDS also allows F8 key to be 
assigned to this function. 


Retrieve 


FQ 


Required on all displays with a command line. 


Command 


FQ 


Used to display a pop-up command line. 
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Table 21-15 (Page 2 of 2). CUA Entry Dialog Actions 
Function Key Usage Requirements 


Cancel F12 Must be active and shown on all displays except: 


e When the previous display was a prompt for a func- 
tion that had already been processed. 

¢ Ona display where only the Exit function is appro- 
priate because the user must not be allowed to exit 
without first verifying (by way of an Exit display) 
whether data is to be saved. 


Left F19 Must be operational on all displays with a horizontal area 
that can be paged. There are no common columns of 
information between these successive views. 


Right F20 Must be operational on all displays with a horizontal area 
that can be paged. There are no common columns of 
information between these successive views. 


Function Key Area and Message Line Relationship: The entry model has the 
message line placed as a separator between other display areas and the function 
key area, and command area if used. A command line would be above the func- 
tion key area and below the message line. 


The guidelines for the function key area do not change, except for placement. A 
single line of function keys is on line 24. Two lines of function keys occupy lines 23 
and 24. The message area is on the line immediately above the function keys. 


Single-Choice Selection (Menu) 
A CUA single-choice selection field displays a list of choices from which the user 
can select one choice. The display always has a title, an instruction, a list of 
choices, and a labeled field for typing the number of the choice selected. 
Figure 21-18 shows an example of a CUA single-choice selection field on a 
display. 


Go To Another List 
Select one of the following: 


Work with documents in folder 
Work with documents to be printed 
Work with folders 

Work with nontext document data 
Work with text profiles 


arWNr 


F3=Exit F12=Cancel 


— — 


Figure 21-18. Example of an Application Menu 
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Selection Choices and Choice Entry Field 
The guidelines for selection choices and the choice entry field are as follows: 


e Begin the choices one blank line after the instruction line. 


¢ Achoice entry field is on line 5 preceding the first choice. The length of a 
choice entry field is one position if the number of choices is less than 10, two 
positions if any choice numbers are 10 or greater (up to 99). 


e The choice entry field starts in position 2. 


e List the choices (one per line) starting in position 4 if the number of options is 
nine or less. The number is followed by a period and is not highlighted. 


e If any choice number exceeds 9, the choice entry field requires 2 characters (in 
positions 2 and 3). Option numbers 1 through 9 start in position 6, and 
numbers 10 and higher start in position 5. 


Guidelines for Single Selection Field Operation 

The single selection field allows two methods of interaction. The user can enter the 
number of the choice in the choice entry field and press the Enter key, or can move 
the cursor directly to the desired choice and press the Enter key. 


Use the following rules: 


e lf the cursor is in the choice entry field, or 1 character position to the right (posi- 
tion 3 or 4), process the choice in the choice entry field. 


e If the cursor is not in or immediately to the right of the choice entry field, and 
the choice entry field contains a blank, process the choice on the same line as 
the cursor. 


e If the cursor is not in or immediately to the right of the choice entry field, the 
choice entry field is not blank (a value has been entered), and the value in the 
field is not the same as the choice being selected, present a message that 
asks the user to choose between the choice being pointed at and the choice 
indicated by the value in the choice entry field. 


Entry Display 
Entry displays let users type in entry fields, and are typically used to indicate the 
system parameters and options associated with an action request. Figure 21-19 
on page 21-54 shows an example of an entry display. 
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Merge Options 
Type choices, press Enter. 

Job queue. .......... 1. Placed on job queue 
2. Not on job queue 
Completion message ...... 1. Message sent 
2. Message not sent 
Job description. ....... + Name 


ADVAN: 2g. cs eet recdey aiedee Name, *LIBL 

Adjust/paginate option _ 1. Do not adjust 

2. Line ending only 

3. Line and page ending 
Report line format ...... _ 1. Multiple lines 

2. No multiple lines 
Footnotes ........2.. _ 1. Collected 

2. Not collected 


F3=Exit F4=Prompt  F12=Cancel 


— — 


Figure 21-19. Entry Display 


Entry Fields 

CUA entry fields take two forms. The first form is an entry field that requests a 
user-supplied value, like a name, descriptive text, or address. Frequently, these 
fields can accept a value from a list of values that is of variable length and con- 
tents. When such a list of valid choices exists, support F4 to allow the user to 
request the list and simply choose from it. 


Using descriptive text (F4 for list) is preferred method for identifying a field sup- 
porting F4. As an alternative, CUA specifies a plus sign (+) to follow the entry field 
(with one intervening blank for an attribute byte) if the field supports F4. 


PAGS 5) Siete sii hen Se eet + Name 


The second type of entry field supports a selection from a fixed set of choices. CUA 
calls this a Selection field. If only one choice can be selected, number the choices. 
For example: 


Type style. .... _ 1. Prestige elite (12 pitch) 
2. Courier (10 pitch) 
3. Essay standard 


The user selects by either moving the cursor or typing in the entry field (see 
“Guidelines for Single Selection Field Operation” on page 21-53). 


If the list of values is more than can be shown in one to five lines, support F4. 


CUA discourages prompts that are phrased to require selection of a Yes or No 
response. For example, for setting printing options, instead of using: 


Duplex .......-. _ 1. Yes 
2. No 


CUA recommends: 
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One or both sides .. _ 1. Both sides 
2. One side 


Selection choices are aligned on the left and shown on separate lines. No comma 
or other punctuation is shown at the end of any line. 


_ 1. Prestige elite (12 pitch) 
2. Courier (10 pitch) 
3. Essay standard (proportional) 
4. Essay bold (proportional) 


Information Display 


A CUA version of the information display shown could be paged instead of being in 
two parts as the AS/400 example shown in Figure 21-7 on page 21-18. Also, the 
explanatory information for Yes and No would not be required because Yes and No 
would not have been used for the entry function for which this information display is 
based. See “List Display” for a discussion of CUA paging information. 

Figure 21-20 shows an example of the sample information display in CUA format. 


View Document Details 


More: + 
Creation date .....: 00000000 
Document ........3 000000000000 
Document description . . : 000000000000000000000000000000000000000000000 
Subject ... . . ~~. « !  0000000000000000000000000000000000000000000000000 
00000000000 
Change formats/ 

options ...... . :  000000000000000 

Authors .... .. . « %  00000000000000000000  0000000000000000000 
Keywords . . . . ~~. . « 0000000000000000000000000000000000000000000000000 


000000000000000000000000000000000000000000000000000000000000000000000000000000 
0000000000000000000000000000000000000000000000000000000 


Document class .....: 0000000000000000 

Print as labels ....: 00000000000 

PYOJOCE. 2 2 4-eh oe aS 0000000000 

Reference ... . . ~~ %  0000000000000000000000000000000000000000000000000 
0000000000 


F3=Exit F12=Cancel 


Figure 21-20. Example of an Information Display 


List Display 
Like the information display, a CUA version of the sample list display would differ 
primarily in the display of paging information. Figure 21-21 on page 21-56 shows 
an example of a list display. 


CUA uses the word More followed by a colon and then paging symbols to indicate 
additional information exists outside the visible area, and the direction to page to 
see that information. 


If the user can page in all four directions, backward, forward, left, and right, reserve 
space for all four paging symbols. If the user can page in only two directions, 
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reserve space for two. Symbols are not shown if the user cannot page in the direc- 
tion they represent; blanks are shown instead. 

The four paging symbols are: 

< indicates there is information to the left 

— indicates there is information backward 

+ indicates there is information forward 


> indicates there is information to the right 


Work with Documents in Folders 


Folder 
Position to. ..... Starting character(s) 


Type options (and Document), press Enter. 


1=Create 2=Revise 3=Copy 4=Delete 5=View 
6=Print 7=Rename 8=Details 9=Print options 10=Send 
11=Spell 12=File remote 13=Paginate 14=Authority 
More: -+ 
Opt Document Document Description Revised Type 


000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 
000000000000 00000000000000000000000000000000000 00000000 0000000000 


F3=Exit F4=Folder list F5=Refresh F6=Print list 
F9=Goto FlQ=Search for document F12=Cancel 


Figure 21-21. Example of a List Display 


According to CUA, the following paging indicators can be used instead of More: - + 
for alternative text paging indicators: 


Top Above the area that is paged when users view the beginning of the 
information 
More Above the area that is paged when users can page backward 


Bottom Below the area that is paged when users view the end of the information 

More Below the area that is paged when users can page forward 

Note: This technique takes extra lines above and below the area that will be 
paged. 


Using CUA defined paging information is not possible when using subfiles. The 
application program itself must handle the paging. See “List Fields” on page 21-24 
for more information. 


The paging method used should be cursor independent when the information is 
paged in fixed amounts. 
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Help Information 


CUA help information resembles AS/400 help information by having a number of 
defined functions available from every help display via function keys. These func- 
tion keys and their functions are: 


F1=Help for help 
F2=Extended help 
F3=Exit 
F5=Tutorial 
F9=Keys help 
F11=Help index 
F14=Tutorial 


These functions cannot be provided by DDS using function keys from help displays. 


For information on DDS capabilities for help information, see “Defining Help Infor- 
mation for All Displays” on page 21-44. 
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Example: Title Citations .................0 0.200200 0048. A-13 
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ReSUIIS® . 2 ode, moter eh OR ee eee be Gee ho eo A-13 
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COND (Condition Definition) ....................2...00.. A-27 
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COPYR (Copyright) ..........0 0.00000 02 eee A-30 
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DATA (Data Presentation Area) ............ 00000000 eee A-31 


Required Attribute .. 2... 2.00.0... ee A-32 


OptionalAttribUtes © soe. oe we Ew eH ey Bee ee a a ae ye A-32 
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WIM: Source. ete ee nee Sa a ee ve ee ee ee Be A-36 
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Optional Attributes ..........2.20 2020002020000 02 ee A-100 
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Tag Language 


Appendix A. UIM Panel Group Definition Language 


This appendix describes the UIM panel group defi- 
nition language. Following some introductory 
material on the nature of the language syntax and 
the structure of the panel group definitions, the 


actual statements of the language, the tags, are 
defined. The tag definitions in this chapter are 
organized alphabetically. 


A sample syntax diagram is shown below: 


p>>—: TAGNAME—VATTR=value 


>< 


| DEFAULT | wpaccontent 
KATTR= HVALU E i 
VALUE2 


The TAGNAME specifies the name of the tag. 
This sample tag has two attributes: VATTR, for 
value attribute; and KATTR, for keyword attribute. 
The second attribute in this example is shown on 
the alternate branch to indicate that it is an 
optional attribute. This attribute can have one of 
three values: DEFAULT, VALUE1, and VALUE2. 


DEFAULT is the value used when you do not 
specify a value for the KATTR attribute. If there is a 
default value, it appears on the group choice line 
above the attribute name, as DEFAULT appears 
on the line above the KATTR attribute name. 
Instead of using the DEFAULT value, you may 
choose either VALUE1 or VALUE2. These values 
are entered as shown in the syntax diagram. 


The value is a value you enter, as specified for 
that attribute. An attribute va/ue must be enclosed 
with apostrophes (') when it contains characters 
other than A through Z or 0 through 9, and it must 
be contained on one source line. To enter an 
apostrophe in a value surrounded by apostrophes, 
type the apostrophe twice. 


The tag-content is text associated with that tag 
that may be displayed or printed for the user. It is 
designed to allow national language translation. 


The period at the end of the tag and before the 
tag content is known as the markup/content sep- 
arator. This separator is required for all tag 
markup. 


The source for a panel group can be entered in 
either lowercase, uppercase, or mixed case char- 
acters. The UIM converts the tag names, attribute 
names, and attribute values to uppercase as 


© Copyright IBM Corp. 1997 


appropriate during the compile process. For 
example, the following uses of the example tag, 
TAGNAME, are equivalent specifications: 


: TAGNAME VATTR=VALUE. 
:tagname vattr=value. 
:Tagname Vattr=Value. 


Tag attributes do not need to be specified in the 
order specified in the syntax diagram. For 
example, the following uses of the example tag, 
TAGNAME, are equivalent specifications: 


:tagname vattr=value kattr=valuel. 
:tagname kattr=valuel vattr=value. 


Sometimes it is necessary to continue the attribute 
of a tag to another source line. However, not all 
attributes can be continued. The attributes in the 
following table are the only ones that can be con- 


tinued. 


Table A-1 (Page 1 of 2). Tag Attributes That Can Be 


Continued 

Attribute Tag 
ACTION KEYI 
ACTION MENUI 
ACTION PDFLDC 
COLHEAD LISTCOL 
COLS LISTVIEW 
CONDS TT 
EMPHASIS LISTDEF 
ENTER LISTACT 
ENTER PANEL 
EXPR COND 
EXTENTER LISTACT 
EXTPROMPT LISTACT 
LINKWHEN LINK 
NOGET VARRCD 
NOPUT VARRCD 


Tag Language 


Table A-1 (Page 2 of 2). Tag Attributes That Can Be 


Continued 

Attribute Tag 
PERFORM LINK 
PROMPT LISTACT 
PROTECT LISTDEF 
RANGE CHECK 
REL CHECK 
ROOTS ISCH 
TOPICS ISCHSUBT 
UNLESSn LINK 
VALUES CHECK 
VALUES TTROW 
VARS LISTDEF 
VARS VARRCD 


To continue an attribute, repeat the attribute on 
the next source line, as in the following example: 


: TAGNAME 
VATTR='valuel value2 value3' 
VATTR='value4 value5 value6' 
VATTR='value7 value& value9'. 
tag-content 


A maximum of fifty attribute names can be speci- 
fied for any tag, including each repeated attribute 
name. 


Tag Content Formatted as 


Paragraphs: The period (.), question mark 
(?), and exclamation point (!) are sentence-ending 
characters. Depending on the national language 
requirements, one or more blanks are placed after 
each of the sentence-ending characters that end a 
UIM source line when the panel group or menu 
object is created. The number of blanks can be 
from one to six, and is specified in the message 
text of the CPIGAB9 message in the message file 
QCPFMSG. 


The following example shows how the CPI6AB9 
message works. 


:p.This is the first sentence. 
This is the second! This is the third. 


In this example, :p. is the tag name. The :p. tag 
does not require attributes. There are three 
spaces between the second sentence and the 
third sentence because of national language 
requirements. If the CPIGAB9 message is set to 
xx, this paragraph appears this way to the UIM 
after it is compiled: 
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This is the first sentence. This is the 
second! This is the third. 


There are two spaces between the first and 
second sentences. There are three spaces 
between the second and third sentences. 


Because the CPIGABY message affects the 
amount of space that follows the end of a source 
line, if the CPIGAB9 message is changed to xxx, 
there will be three spaces between each sentence 
in the previous example. 


Note: The CPI6AB9 message should already be 
translated to the proper number of x's for your 
country. 


Panel Areas: The five types of panel areas 
are menu, information, data, list, and text areas. 
A mixed panel is constructed by using two or 
more of these areas within the same panel. 


The restrictions associated with mixed panels are 
listed in Table A-2. 


Table A-2. Restrictions Associated With Mixed Panels 


Menu Info Data Non- Action Text 
Action _ List 
List 
Menu No Yes Yes Yes No No 
Info Yes Yes Yes Yes Yes No 
Data Yes Yes Yes Yes Yes No 
Non- Yes Yes Yes Yes Yes No 
Action 
List 
Action No Yes Yes Yes No No 
List 
Text No No No-~ No No No 


All of these area types can be scrolled. Scrolling, 
as well as presentation of the appropriate scroll 
location information, is handled by the UIM for 
menu, information, data, and list areas. Scrolling 
for text areas is handled by the text area user exit 
program. 


Panels: A panel is made up of one or more 
panel areas, each of which has a specific layout 
and function. Specific panels are usually categor- 
ized according to the nature of their application 
areas, such as information panels, menu panels, 
list panels, and text panels. 


Panel Group Objects: A panel group is a 
logical grouping of panels that can correspond to 
a software product, a command, or a related col- 
lection of commands or other services. It can 
contain panels of any type. Panel groups provide 
a context for names of panels, variables, list defi- 
nitions, and help modules. 


Tag Language 


Help on Panels: Help for a panel is con- 
structed from help modules referred to in the 
panel definition. Extended help for a panel is a 
concatenation of the help for the panel, the menu 
bar, items in all areas in the order of their defi- 
nitions, and function keys in the order of their defi- 
nitions. 
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Tag Language 


Panel Group Organization 


The following list shows the required order of tags 
in the UIM source for panel groups and menus. 


;—— Panel Group Outline 
Panel Group (PNLGRP) 


e Prolog section 
Copyright statement (COPYR) 
Import statements (IMPORT) 
Class definitions (CLASS) 
Variable definitions (VAR) 
Variable Record Definitions (VARRCD) 
List definitions (LISTDEF) 
Condition definitions (COND) 
Truth table definitions (TT) 
Menu bar definitions (MBAR) 
Key list definitions (KEYL) 
¢ Body section 
Display panel definitions (PANEL)! 
— Area definitions (MENU, INFO, 
DATA, LIST, TEXT) 
— Command and option line defi- 
nitions (CMDLINE, OPTLINE) 
Print head panel definitions 
(PRTHEAD)! 
— Area definitions (INFO, DATA) 
— Print trailer message (PRTTRAIL) 
Print panel definitions (PRTPNL)' 
— Area definitions (INFO, DATA, 
LIST) 
Help module definitions (HELP)! 


A UIM menu, created with the Create Menu 
(CRTMNU) command, is a special form of panel 
group. These menus are limited to the following 
panel group tags: 


-—— UIM Menu Outline 
Panel Group (PNLGRP) 


e Prolog section 
Copyright statement (COPYR) 
Import statements (IMPORT) 
Variable definitions (VAR) 
Condition definitions (COND) 
Truth table definitions (TT) 
Menu Bar (MBAR) 
Key list definitions (KEYL) 
¢ Body section 
Panel definitions (PANEL)? 
— Area definitions (MENU, INFO, 
DATA) 
— Command and option line defi- 
nitions (CMDLINE, OPTLINE) 
Help module definitions (HELP)? 


Name Syntax 


There are several elements, identified with tags, 
within a panel group that can be named so that 
they can be referred to from other elements within 
that panel group, such as classes, dialog vari- 
ables, lists, and conditions. The application 
program can also refer to named elements by 
passing the name to the UIM as a parameter on 
an application programming interface (API) call. 
These elements have a NAME attribute on the tags 
that define them. These names may be up to 10 
characters long and can contain only the charac- 
ters A through Z and 0 through 9. The first char- 
acter of a name must be an A through Z 
character. 


Names of help modules defined by the HELP tag 
can be up to 32 characters long and are defined 
in the same name space as other elements. As a 
result, a help module and another element cannot 
have the same name in a panel group. They can 
contain the characters A through Z, 0 through 9, 
slash (/), and underscore (_). If the name con- 
tains a slash or an underscore, it must be 
enclosed between apostrophes. The first char- 
acter of a help name must be an A through Z 
character, a slash, or an underscore. 


1 PANEL, PRTHEAD, PRTPNL, and HELP tags can be used in any order. 


2 The PANEL and HELP tags can be used in any order. 
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Because all names are stored in the panel group 
object in uppercase format, lowercase alphabetic 
characters (a through z) are converted to upper- 
case alphabetic characters (A through Z). When 
the name of an element is passed to the UIM 
through an application program interface, the 
name must be passed in uppercase characters. 


Because these names stay within the panel group 
and reside in the same name space, a dialog vari- 
able and a UIM list cannot have the same name. 


There is an occasional need to refer to object 
names in the panel group source. These names 
must obey the rules for OS/400 object names. 
They must be enclosed between apostrophes 
when they contain characters other than A through 
Z and 0 through 9. 


Symbols 


A symbol is a name that can be replaced with 
something else while the panel group is compiling. 
All symbols use an ampersand (&), followed by 
the symbol name, followed by a period. Symbols 
must appear in the text following the period of a 
tag. 


Symbols can be entered in either uppercase or 
lowercase. 


The following symbols are defined by the UIM: 


&amp. Creates an ampersand (&) without trig- 
gering symbol processing. This symbol 
is used when an ampersand is needed 
in the text of a tag. If this symbol is 
not used, the UIM replaces the symbol 
name with its actual value. 


>>—&amp. >< 
&colon. Creates a colon (:) without triggering 

tag processing. This symbol is used 

when a colon is needed in the text of a 

tag. 

>>—A&colon. >< 
&cont. Forces the concatenation of the next 


source line with the current source line. 
Concatenation occurs only when the 
symbol is the last character in a source 
line. No visible symbol is created for 
the &cont. symbol. 


Tag Language 


When the &cont. symbol is used to 
continue the two parts of a double-byte 
character set (DBCS) word, both the 
ending shift-in character of the first line 
and the starting shift-out character of 
the second line are discarded. 


The &cont. symbol is useful with a 
figure, a line, or an example. The 
symbol can be used when a CIT, HPn, 
or LINK tag would cause the resulting 
source line to be longer than the length 
of the source record. 


Here is an example of how to use the 
&cont. symbol. 


:LINES. 

Text to be continued &cont. 

:LINK perform='dsphelp hyper' 
linkwhen='chkusrcls("*PGMR")'.&cont. 
reference phrase&cont. 

:ELINK.&cont. 

more text on line. 

:ELINES. 


>>—&cont. >< 


&msg(msgid,msgf,lib). 
The compiler extracts the first-level 
message text for the message MSGID 
from the message file MSGF in library 
LIB and substitutes the text in place of 
this symbol. The message text is 
retrieved in the CCSID of the panel 
group source file without any substi- 
tution variables. 


The message file defaults to the 
message file specified on the SUBMSGF 
attribute of the PNLGRP tag. If 
SUBMSGF is not specified, the message 
file must be specified in the symbol. 


>>—&msg (msgid > 


> 


| ). >< 


| 
»msgf- 
Lie 


&period. Creates a period (.) in the text. This 
symbol is used when a period is 
needed in column one of the text 
without triggering control word pro- 
cessing. 


>>—A&period. >< 
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Tag Language 


&slr. Creates a right slash (/) in the text. 
This symbol is used if a right slash is 
needed in column one of the tag 
source. If this symbol is not used, right 
slashes in column one of the source 
file can cause problems if the source 
file is part of the input stream for a 
batch job. 


>>—Aslr. >< 


Comments 


In addition to markup done with tags, comments 

can also be inserted into the source of the panel 

group. Typically, comments are used to describe 
the content of the file, or to give information as to 
the structure, format, date, author, and so on. 


Comments begin with a period followed by an 
asterisk (.*). They must be used in columns one 
and two of the source record. They are ignored 
by the compiler, but are listed in the source listing. 
They are not preserved in the panel group object. 
An example using comments follows: 


a REKKKKEKKEKEKKEKRKEKKK ERK RR KEKE ER EKER RRR EKER 
.* panel group XXX. XXX 

.* author X. X. XXXXXXX 

.* change history 9/18/92 (xxx) Created 


a RREKKKKEKKEKEKKEKEKKKK KKK KKK KER EKKKRKKERKERKEREKEK 


:pnigrp ... 


:epnigrp. 


Imbeds 


Source from other files can be brought into a 
panel group at the time the panel group is com- 
piled. This allows you to create a panel group or 
menu from multiple source file members. Imbeds 
are done with the .IM control word. An example 
using imbeds follows: 


.im member1 


The member (member 1) in the file named in the 
include file (INCFILE) parameter on the Create 
Panel Group (CRTPNLGRP) or Create Menu 
(CRTMNU) command is opened and processed as 
if it appeared in the original source file. Imbeds 
can be nested up to 10 deep; attempting to nest 
deeper than 10 results in an error and the panel 
group or menu object is not created. 
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DBCS Graphic Literals 


DBCS graphic literals are supported by the UIM to 
support processing of strings of literal characters 
of DBCS graphic data. The syntax of the literals 
follows: 


r>—"shi ft-outts_+p-al chi ft inS-"—g—»<« 


Notes: 

1 Shift-out is X'0E' 

2 Dis one DBCS character 
3 Shift-in is X'OF' 


The value must be enclosed in apostrophes 
because it contains special characters. 


All strings of literal characters coded on UIM tags 
that are compared against a DBCS graphic field 
must be in the form of DBCS graphic literals. The 
shift-out and shift-in characters are removed from 
the graphic strings before the comparison is per- 
formed. 


Caution should be used when literals are com- 
pared to input-capable graphic fields. You must 
realize that on a nongraphic DBCS device, there 
are two fewer bytes available for input. As a 
result, you should always use literals that are two 
bytes less than the maximum length of the entry 
field of the DBCS graphic variable. 


When DBCS graphic characters are used after the 
period of a tag, (such as on the translation list 
item (Tl) tag) a graphic literal should not be used. 
What should be used is everything between and 
not including the quotation marks in the diagram 
above. 


Hexadecimal Literals 


Hexadecimal data can be entered in attributes 
wherever a character string literal is allowed. The 
syntax of hexadecimal literals follows: 


>> u a xX (1) u X: >< 


Note: 
' xx is a pair of hexadecimal digits (0 through 9, a 
through f, or A through F) 


The following example shows how to code a 
hexadecimal value for a translation item. 


Tag Language 


:TI value='"01"x'.*YES The value must be enclosed in apostrophes 
:TI value='"02"x'.*NO because it contains special characters. 
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APPFMIT tag 


APPFMT (Application Formatted Area) 


> 


>>—: APPFMI—VAR=dialog-variable-name—WIDTH=area-width—DEPTH=area-depth > 


>< 


Lusrexit= ‘CALL program-reference fl 


The application formatted area (APPFMT) tag is 
an optional tag which defines an area in the upper 
right corner of a menu area to be formatted by the 
application. Only one APPFMT tag can be speci- 
fied in each menu area. It must immediately 
follow the menu area (MENU) and top instruction 
(TOPINST) tags. 


The application formatted area is part of the menu 
area, appearing at the right edge of the menu 
area and ending one character position before the 
right edge of the panel. The width is determined 
by the WIDTH attribute of this tag. The application 
formatted area extends from the blank line fol- 
lowing the top instruction lines of the menu area to 
the number of lines defined in the DEPTH attribute 
of this tag. A two-byte separator is maintained 
between the menu item descriptions and the appli- 
cation formatted area. 


If the depth of the application formatted area is 
less than the depth of the menu area, the area 
below the application formatted area and to the 
right of the menu area is blank. The depth of the 
application formatted area may not be greater 
than the depth of the menu area. 


If the menu area is scrollable, the scroll indicators 
appear to the left of the separator between the 
menu area and the application formatted area. 
You cannot scroll the application formatted area, 
even if you can scroll the menu area. 


The application formatted data is described in 
“Application Formatted Data” on page A-9. 


Extended help for the panel is displayed if the 
Help key is pressed while the cursor is in the 
application formatted area. 


Required Attributes 


VARz=dialog-variable-name 
The name of the dialog variable containing the 
application formatted area. Define the dialog 
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variable using a class definition (CLASS) tag 
with a BASETYPE of CHAR x, where x equals 
the product of the area width times the area 
depth. 


You can use the exit program for application 
formatted data, specified on the USREXIT attri- 
bute of this tag, to update this dialog variable 
each time the panel is displayed. The UIM 
uses the value of the dialog variable as the 
application formatted data, described in “Appli- 
cation Formatted Data” on page A-9. 


WIDTH=area-width 
The width, in characters, for the application 
formatted area associated with the menu area. 
The width specified must be an integer in the 
range of 1 to 40, or the panel width minus 17, 
whichever is less. 


DEPTH=area-depth 
The depth, in lines, of the application for- 
matted area. This depth must be no greater 
than the number of lines available for the body 
of the menu. The body of the menu is the 
area between and excluding the top instruc- 
tion line and the bottom instruction line or 
bottom separator. 


Optional Attribute 


USREXIT='CALL program-reference' 
The exit program for application formatted 
data, called to update the value of the dialog 
variable containing the application formatted 
data each time the panel is displayed. 


For a description of the CALL dialog 
command, see Appendix B, “UIM Dialog 
Commands’ on page B-1. 


For a description of the interface between the 
UIM and the exit program for application for- 
matted data, see the System AP! Reference. 


Application Formatted Data 


The dialog variable containing the application for- 
matted data is specified on the VAR attribute of 
this tag. The contents of this variable is viewed 
by the UIM as a d by w array of characters, where 
dis the depth and wis the width of the application 
formatted area. Each row of the array is dis- 
played as one line of the application formatted 
area. 


Any character within the data can be a selection 
character for a highlighting class. Only output and 
text classes are allowed in an application for- 
matted area; no input fields are allowed. The 
class selection applies to the following characters 
up to another class selection character or the end 
of the row, whichever occurs first. The UIM sets 
the highlighting class to normal text at the begin- 
ning of each row of the area. 


The selection characters for highlighting are in the 
range of X'01' through X'06'. The following 
selection characters for highlighting are recog- 
nized by the UIM: 


X'01' Normal variable output 

X'02' De-emphasized variable output 
X'03' Emphasized variable output 
X'04' Normal text 

X'05' De-emphasized text 

X'06' Emphasized text 


The UIM replaces each class selection character 
with the appropriate display attributes for the 
class. Other character values in the ranges X'01' 
through X'06', and X'10' through X'3F', as well 
as X'FF', are converted to X'1F', appearing as a 
reverse image box on the screen. Characters 
X'00' (null), X'OE' (shift-out for double-byte), 
X'OF' (shift-in for double-byte), and X'40' 


APPFMT tag 


through X'FE' (normal, displayable characters), 
are passed unchanged to the screen. 


The UIM inserts a normal text attribute before 
each line of the application formatted area and a 
field-ending attribute after each line of the applica- 
tion formatted area. This effectively isolates the 
application formatted area from the rest of the 
panel with respect to highlighting attributes. 


No character set and code page conversion is 
done on the application formatted data. If conver- 
sion is necessary, it must be done by the applica- 
tion. 


When the UIM calls the exit program to format the 
application area of a menu, it passes a value 
which identifies the BIDI attribute on the panel 
group (PNLGRP) tag and the code page number 
of the display device. 


The NBRSHAPE and SYMSWAP attributes of the 
CLASS tag used for the application formatted area 
are determined from the class of the dialog vari- 
able containing the application formatted data. 


Example: Application Formatted 
Area 


OfficeVision/400 
System: — SYSNAMXX 
Select one of the following: 


. Calendars Time: 9:09 
. Mail 


1 
2 
3. Send message February 1992 
4. Send note SMTWTFS 
5. Documents and folders i 
6. Word processing 293° #25 65 7 8 
7 9 10 11 12 13 14 15 
8 16 17 18 19 20 21 22 
9 23 24 25 26 27 28 29 


. Directories/distribution lists 
. Decision support 
. Administration 


90. Sign off 


Bottom 
Press ATTN to suspend a selected option. 
Selection 


F3=Exit F12=Cancel F19=Display messages 
(C) COPYRIGHT IBM CORP. 1985, 1991. 
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BOTINST Tag 


BOTINST (Bottom Instruction) 


>>—: BOTINST 
LENT edi aneae ani yprednanc 


>< 
Lauemetionaed. 


The bottom instruction (BOTINST) tag specifies 
the bottom instruction lines for an area of the 
panel. This tag appears immediately before the 
ending tag for the area. You can use multiple 
bottom instruction tags to present multiple instruc- 
tion lines if the tag contains instruction text after 
the period. If multiple tags are coded, no blank 
lines appear between the text on different tags. 
Only one bottom instruction tag is allowed per 
area if the INST attribute is used on this tag. 


If you do not specify a BOTINST tag for an area, 
no instruction line is allocated for the area. 


For menus and information areas, a blank line is 
always left between the body of the area and the 
instruction lines. If you can scroll the area, a 
blank line is reserved for the scroll information 
between the body of the area and the bottom 
instruction. For information about how instruction 
lines are formatted with respect to the body of 
data and list areas, see the BODYSEP attribute in 
“DATA (Data Presentation Area)” on page A-31 
and “LIST (List Area)” on page A-82. 


Optional Attribute 


INST=dialog-variable-name 
The name of a dialog variable that contains 
the bottom instruction text to be displayed. 
The dialog variable must be defined with a 
width less than or equal to the width specified 
on the panel tag minus 2. If the INST attribute 
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is used, no instruction-text can be specified for 
this tag. 


Dialog variables must be defined with a 
BASETYPE of CHAR, IGC, or BIN on the class 
definition (CLASS) tag. 


The error state of the dialog variable is not 
used for determining the highlighting of the 
text. 


Special formatting for IGC. (The abbrevi- 
ation IGC is used in commands and keywords 
to represent double-byte character set func- 
tions.) When a dialog variable with a 
BASETYPE of IGC is specified on the CLASS 
tag, the UIM does special formatting. If the 
dialog variable value begins with a shift-out 
character (X'0E'), the UIM shifts the value 
one byte to the left to preserve vertical align- 
ment with other lines. 


Optional Text 


instruction-text 
The text appearing as bottom instructions for 
the area. The text is an implied paragraph. 
When the display is formatted, any text that 
does not fit onto one display line is formatted 
on multiple lines as necessary and indented 
two display positions. The text can be a 
maximum of 255 characters, and can contain 
only the reverse text (RT) tag. The instruction 
text is required unless the INST attribute is 
specified on this tag. 


CHECK Tag 


CHECK (Validity Checking) 


p>—:CHECK—MSGID=message-identifier 7 > 
Lig Ge=tailal qi edmee sagesyieename! 
“i (et... 
RANGE='—-value! value2 L REL='—*-relop value——' 
> I ] ‘ >< 
VALUES='¥-yalue—L 


The validity checking (CHECK) tag is used within 
a class definition to specify validity checks associ- 
ated with variables of that class. 


Validity checking occurs on input of the variable 
value and after translation list processing. Ifa 
translation list is specified for this class and can 
be applied to an input value, no validity checking 
is performed on the translated input value. If the 
translation list is not applicable and indicates no 
error, the validity checks defined by this tag are 
applied to the input value. For more information 
on using the CHECK tag with translation lists, see 
“TI (Translation List Item)” on page A-158 and “TL 
(Translation List)” on page A-159. 


At least one RANGE, REL, or VALUE attribute of this 
tag must be coded. If more than one validity 
check is coded on the tag, the value must pass 
only one of the check attributes to be accepted for 
this check. If more than one CHECK tag is used, 
a value must pass all the check tags to be 
accepted. Operations from multiple attributes are 
ORed together. 


Required Attribute 


MSGID=message-identifier 
The message identifier of the error message 
displayed to the user if a validity check fails. 
The message should have no substitution var- 
iables defined, because the UIM does not 
supply replacement text when the message is 
sent. 


Optional Attributes 


MSGF=' qualified-message-file-name' . 
The message file that contains the message 
specified on the MSGID attribute of this tag. If 


the DFTMSGF attribute is not specified on the 
panel group (PNLGRP) tag, this attribute must 
be specified. 


RANGE=' value? value2' 
A range check is valid for both character and 
numeric types. The check passes if the value 
entered by the user is greater than or equal to 
value? and less than or equal to value2. This 
attribute can be specified more than once. 


Each value must be numeric or character to 
match the BASETYPE of the variable as speci- 
fied on the class definition (CLASS) tag, and 
cannot be a dialog variable. All character 

values must be enclosed in quotation marks. 


REL=' relop value' 
A relational check is valid for both numeric 
and character types. This attribute can be 
specified more than once. 


Each value must be numeric or character to 
match the BASETYPE of the variable as speci- 
fied on the CLASS tag, and cannot be a 
dialog variable. All character values must be 
enclosed in quotation marks. 


Relational operators are listed below. All 
operators are valid for both character and 
numeric types. The check is affected by the 
CASE and BLANKS attributes of the CLASS tag. 


= Equal. The check passes if the value 
entered by the user is equal to this literal 
value. 


== Not equal. The check passes if the 
value entered by the user is not equal to 
this literal value. 


> Greater than. The check passes if the 
value entered by the user is greater than 
this literal value. 
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CHECK Tag 


< Less than. The check passes if the 
value entered by the user is less than 
this literal value. 


>= Greater than or equal. The check 
passes if the value entered by the user is 
greater than or equal to this literal value. 


<= Less than or equal. The check passes 
if the value entered by the user is less 
than or equal to this literal value. 


The relational operator may be specified as =, 
n=, >, <, >=, Or <=, if the code page of the 
source maps the not character (7) to X'5F'. 
Otherwise, it is suggested that the special 
values *EQ, *NE, *GT, *LT, “GE, or *LE be 
used, respectively, for the relational operator. 


VALUES=' value? value2 ... value-n' 
A values check is valid for both character and 
numeric types. The check passes if the value 
entered by the user is equal to one of the 
values in the list. Checking on character 
values is affected by the CASE and BLANKS 
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attributes of the CLASS tag. The VALUES attri- 
bute can be specified more than once, and up 
to 50 values can be specified for this tag. 


Each value must be numeric or character to 
match the BASETYPE of the variable as speci- 
fied on the CLASS tag, and cannot be a 
dialog variable. The values in the list are sep- 
arated by blanks. All character values must 
be enclosed in quotation marks. 


Example: Validity Checking 


UIM Source 


:CHECK RANGE='1 10' REL='= 99' MSGID=USRO234. 
:CHECK REL='< 5' REL='> 10' MSGID=USR1234. 
:CHECK VALUES='"*YES" "*NO"' 

MSGID=MMM0001 MSGF=USRMSGF. 


The range check allows values 1 through 10, or 
99, for any variables of the class to which it 
applies. The relational check allows values less 
than 5 or greater than 10. The values check 
accepts two special values. 


CIT Tag 


CIT (Title Citation) 


pe—:CIT. :ECIT. 


lige ectexe 


>< 


The title citation (CIT) tag identifies the title of a 
publication and requires a matching end tag. This 
tag is only allowed in information areas and help 
areas. Title citations are underscored for online 
and printed text, and can occur anywhere in the 
text. 


The CIT and ECIT tags must be specified on word 
boundaries. If the two characters immediately fol- 
lowing the ECIT tag are a punctuation mark and a 
blank, the UIM extends the emphasis attribute to 
include the punctuation mark. This allows the 
punctuation mark and the title to be displayed 
using the same emphasis. 


Optional Text 


title-text 


Although the title to be cited is not required, 
the tag has no meaning when no title is speci- 


fied. 
Example: Title Citations 


UIM Source 


:P.For more information about the UIM, 


see the :cit.Application Display Programming:ecit. 


Results 


For more information about the UIM, 


see the Application Display Programming book. 
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book. 


CLASS Tag 


CLASS (Class Definition) 


>>—: CLASS—NAME=c lass-name—BASETYPE= 


"CHAR n' > 
'IGC n | j 


OPEN 
LertHer 
"GRAPHIC w c' 
"NAME n , 
SINPLE——| 
GENERIC 


‘OBUNAME n : 


'BIN b! 
‘PACKED t f' 
‘ZONED t f' 
‘PTR! 
‘DATE! 
‘TIME! 
‘ACTION! 


| > 


LipTH=display-width | | CHRID= L 


NONE [| SHIFT=——NONE 
PNLGRP_ Lupper_! 


Lcase= isl : | | : | 
CASE=—-MIXED BLANKS=——RESPECT SUBST=——DISPLAY 
L upper ~Cenore— L quote 


RTL 
:ECLASS. 


| BIDI=——PNLGRP Ba CONTXTREV= ee zi 
Lite— YES 


> 
T | NBRSHAPE=——PNLGRP 
- Farserc 
HINDI 


L syswaP-—-No 
YES 


>< 


The class definition (CLASS) tag defines variable 
types in variable pools and on panels. Attributes 
of the CLASS tag define the data type for the 
class of the dialog variable and the validity 
checking necessary for all variables of that class. 
The attributes of this tag also determine the 
methods for mapping an internal dialog variable of 
a particular class to or from a displayed form. 


Other tags can be nested within the CLASS tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 
appear and specifies on which page more infor- 
mation can be found about each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
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order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-3. Tags Allowed Between the CLASS and 
ECLASS Tag 


Tag Name Order Page 
TL 1 A-159 
(Translation list) 

CHECK 2 A-11 


(Validity checking) 


Required Attributes 


NAME=class-name 
The name assigned to the class. For more 
information on the rules for naming, see 
“Name Syntax” on page A-4. 


BASETYPE 
The base data type for variables in the class. 
The BASETYPE for a class determines the 
internal storage representation and basic input 
and output editing characteristics for variables 
of a class. 


CHAR n 
Variables of this class are character 
strings of a fixed length. The number of 
bytes, n, is from 1 to 32 767. 


IGC n [OPEN | EITHER] 
Variables of this class are fixed-length 
character strings which may contain 
double-byte data surrounded by shift-out 
and shift-in characters. The number of 
bytes, n, is from 4 to 32 767. 


OPEN indicates that variables defined with 
this class can contain both single-byte and 
double-byte data. 


EITHER indicates that variables defined 
with this class can contain single-byte or 
double-byte data, but not both. If EITHER 
is specified, the number of bytes, n must 
be an even number. 


The CASE attribute on this tag is not 
allowed for IGC classes. For IGC classes, 
processing for CHRID=PNLGRP on this tag 
depends on whether or not the field value 
contains double-byte character set 
(DBCS) data. 


A dialog variable with a BASETYPE of IGC 
can be presented on a device that is not 
DBCS-capable, as long as the panel 
group object in which the variable is 
declared does not have TEXTMODE=DBCS 
specified on the panel group (PNLGRP) 
tag. This allows the same panel group 
object and application to support both 
single-byte character set (SBCS) and 
DBCS field values as long as the prede- 
fined text in the panel group is only SBCS. 


GRAPHIC wc 
Variables of this class can contain only 
DBCS characters which are not sur- 
rounded by shift-out and shift-in charac- 
ters or UCS-2 characters. The number of 
DBCS characters or UCS-2 characters, w, 
is from 1 to 16 383 (1 DBCS character 
equals 2 bytes). The CCSID, c, should 
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only contain a CCSID using the UCS-2 
encoding scheme. 


The contents of a GRAPHIC dialog variable 
must only be DBCS data or UCS-2 data. 
When GRAPHIC is specified on this tag and 
the CCSID parameter is not specified, the 
field will contain graphic DBCS data. 
When GRAPHIC is specified on this tag and 
the CCSID parameter is specified with a 
CCSID using the UCS-2 encoding 
scheme, the field will contain UCS-2 data. 
In both cases, shift-out and shift-in charac- 
ters are not placed in the variable pool by 
either the application or the UIM. On 
output, the UCS-2 data will be converted 
from the specified UCS-2 CCSID to the 
CCSID of the device. On input, the data 
will be converted from the device CCSID 
to the specified UCS-2 CCSID. 


When the CCSID parameter is specified, 
several restrictions are enforced. First, all 
graphic fields using the CCSID parameter 
will not be allowed to span multiple lines 
on a print panel. The COND tag will be 
limited to comparing other variables of the 
same UCS-2 Level 1 encoding scheme. 
UCS-2 dialog variables will not be allowed 
on the CMD dialog command. Also, the 
following tags will not be allowed. 


e CHECK tag 
e TI tag 


As in current graphic DBCS support, each 
UCS-2 character is 2 bytes long. Since 
the length of data displayed on the device 
after a conversion from a UCS-2 CCSID 
to the device CCSID is dependent upon 
what CCSID the device is capable of, the 
WIDTH attribute can be used to provide a 
more accurate field width. This will allow 
you to bypass the default field width to 
either avoid truncation of field data or to 
increase the display space on the screen 
by decreasing the field length. 


When the optional WIDTH attribute is not 
specified in conjunction with the GRAPHIC 
basetype with the CCSID parameter, the 
number of characters on the screen is two 
times the number of UCS-2 characters. 
When the WIDTH attribute is specified in 
conjunction with the GRAPHIC basetype 
with the CCSID parameter, this value will 
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be used for the field length instead of 
default field width. The value entered for 
the WIDTH attribute represents the 
number of UCS-2 characters that would 
be displayed on the screen. 


For example, a panel group contains the 
following line: 


:class name=example 
basetype='graphic 10 X' width=Y. 


X is the UCS-2 CCSID that the data is 
stored as. Y is the width of this field. 
If Y was not specified then the length 
of the field on the screen is 20 (two 
times the number of UCS-2 charac- 
ters). 

If you know that the UCS-2 data is 
constructed from single-byte data, 
then the field width, Y, could be speci- 
fied as 5 UCS-2 characters so that the 
field would have a width of 10 single- 
byte characters on the screen. 

If you know that the UCS-2 data is 
constructed from double-byte data, 
then the field width, Y, could be speci- 
fied as 11 UCS-2 characters so that 
the field would have a length of 22 
single-byte characters on the screen. 
This would allow space for the 
shift-out and shift-in characters. 


On output, field data that is longer than 
the specified field length will be truncated. 
On input, if too many characters were 
entered into the UCS-2 field, then the field 
will be reverse image and an error will 
appear on the error line stating too many 
characters were entered. The maximum 
number of characters to enter will be dis- 
played in the error message. 


Variables defined with the UCS-2 
basetype are not allowed on print panels. 


NAME rn [SIMPLE | GENERIC] 
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Use a BASETYPE of NAME for System/38 
names and names which follow the same 
rules as System/38 object names, such as 
names of record formats. 


Lowercase characters (a through z) are 
converted to upper case characters (A 
through Z) according to the same rules 
that commands follow. For more informa- 
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tion on converting lowercase characters to 
uppercase characters, see the CL Refer- 
ence. 


The number of bytes, n, is from 1 to 255. 


SIMPLE indicates that the name entered 
must be allowed as a simple OS/400 
name. 


GENERIC indicates that the name must 
be a syntactically correct OS/400 generic 
name. 


A translation list must be specified in the 
class definition if blanks or any other 
name value that is not valid is allowed as 
an input value for a dialog variable of this 
BASETYPE. 


OBJNAME rn [SIMPLE | GENERIC | POSTO] 


Use a BASETYPE of OBJUNAME for OS/400 
object names. SIMPLE indicates that the 
name entered must be a single OS/400 
object name. 


GENERIC indicates that the name must 
be a syntactically correct OS/400 generic 
object name. 


POSTO indicates that the name is used 
for a position-to field, and does not have 
to be a syntactically correct OS/400 name. 
Lowercase characters (a through z) are 
converted to uppercase characters (A 
through Z) unless the name is enclosed in 
double quotation marks. The number of 
bytes, n, is from 1 to 255. 


When POSTO is specified, if the first and 
last character of the name is a double 
quotation mark, the last double quote is 
removed from the name. If the first char- 
acter is not a quotation mark, all lower- 
case characters (a through z) are 
converted to uppercase characters (A 
through Z). When POSTO is specified, 
the name does not have to be a valid 
object name. 


A translation list must be specified in the 
class definition if blanks or any other 
name value that is not valid is allowed as 
an input value for a dialog variable of this 
BASETYPE. For example, a translation list 
is necessary when *LIBL should be an 
allowed value for a variable containing the 
library name. For an example of a trans- 


lation list, see “TL (Translation List)” on 
page A-159. 


The CASE attribute on this tag cannot be 
specified for an object name class. The 
UIM automatically adds or removes delim- 
iter characters (quotation marks) and con- 
verts lowercase input values to uppercase 
as necessary. 


BIN b 


Variables of this BASETYPE are signed and 
unsigned binary numbers. The number of 
bits, b, is either 15, 16, 31, or 32. 


‘BIN 15' and 'BIN 31' are signed binary 
numbers. 'BIN 16' and 'BIN 32' are 
unsigned binary numbers. 


‘BIN 15' is the same as BINARY(2) and 
‘BIN 31' is the same as BINARY(4), as 
described in chapter two of the System 
API Reference. 


PACKED [ f 


Variables of this class are packed decimal 
numbers. The number of digits, ¢, is from 
1 to 31. The number of decimal positions, 
f, is from 0 to t. 


ZONED [ f 


Variables of this class are zoned decimal 

numbers. The number of digits, ¢, is from 
1 to 31. The number of decimal positions, 
f, is from 0 to t. 


PTR 


Variables of this class are pointers. Any 
variables of this BASETYPE cannot be dis- 
played or printed. The data pointed to by 
a PTR variable can be displayed in a text 
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area. For more information on text areas, 
see “TEXT (Text Area)” on page A-154. 


DATE 


The variable is a 7-byte string repre- 
senting the date in the form cyymmadd. 
The date abbreviations are represented as 
follows: 


c Century. Zero indicates the twentieth 
century and one indicates the twenty- 
first century. 

yy Year 

mm Month 

dd Day 


TIME 


A value of this class is a 6-byte string 
representing the time in the form hhmmss. 
The time abbreviations are represented as 
follows: 


hh Hours 
mm Minutes 
ss Seconds 


ACTION 


The variable is a 2-byte binary number 
with the same internal form as BIN 15, 
used as the option column for an action 
list or the selection column for a selection 
list. 


When a variable with this BASETYPE is 
specified for the VAR attribute on a list 
column (LISTCOL) tag for an action list, 
the UIM determines the width of the input 
field based on the maximum OPTION attri- 
bute value specified for any list action 
(LISTACT) tag in the area. 
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Table A-4. Attribute Summary for Each BASETYPE 

BASETYPE Default Minimum Maximum Default Default Default 
WIDTH WIDTH WIDTH SHIFT CASE BLANKS 
Attribute Attribute Attribute Attribute Attribute Attribute 

BIN 15 6 1 255 UPPER UPPER IGNORE 

BIN 16 5 1 255 UPPER UPPER IGNORE 

BIN 31 11 1 255 UPPER UPPER IGNORE 

BIN 32 10 1 255 UPPER UPPER IGNORE 

CHAR n n n 32767 NONE MIXED RESPECT 

IGC n n n 32767 NONE MIXED RESPECT 

GRAPHIC w w w 16383 NONE MIXED RESPECT 

GRAPHIC we w w/2 16383 NONE MIXED RESPECT 

NAME n n n 255 UPPER UPPER IGNORE 

OBJNAME n n n 255 NONE See text IGNORE 

PACKED t f 43 A838 255 UPPER n/a n/a 

where t=f 

PACKED t f 2 f2 255 UPPER n/a n/a 

where th=f and £0 

PACKED t f t+ 1 255 UPPER n/a n/a 

where th=f and £0 

ZONED t f 43 A838 255 UPPER n/a n/a 

where t=f 

ZONED tf 2 f2 255 UPPER n/a n/a 

where th=f and £0 

ZONED t f t+ 1 255 UPPER n/a n/a 

where th=f and £0 

DATE 8 8 255 UPPER n/a n/a 

TIME 8 8 255 UPPER n/a n/a 

ACTION 6 (See 1 255 UPPER UPPER IGNORE 
text) 

Optional Attributes For more information on translation lists, see 


“TL (Translation List)” on page A-159. 
WIDTH=display-wiath. 


The width of a display field in which values of CHRID=NONE | PNLGRP 

this class are presented. For a BASETYPE of If the CHRID parameter on the CRTPNLGRP 
GRAPHIC, this value is the number of DBCS command is “JOBCCSID, the compiler issues 
characters or UCS-2 characters. The defaults a warning message and the CHRID attribute 
and allowable values for the display width on the CLASS tag is ignored. All variables 
depend on the BASETYPE attribute, as specified are converted from the job CCSID to the 

in Table A-4. device CHRID when *JOBCCSID is specified. 
For variables that use this class, a value If NONE is specified, the data is assumed to 
larger than the default for the BASETYPE may be in the correct character set and code page 
be needed to support the external display for the display or printer device. 

form of values appearing in a translation list. If PNLGRP is specified, the data associated 


with this class is interpreted with the character 
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set and code page specified on the CHRID 
parameter on the CRTPNLGRP control lan- 
guage command. For devices that do not 
allow the downloading of this code page to 
handle the display of such data, character 
conversion occurs on both output and input for 
variables of this class. The conversion table 
for such cases is determined by the following 
rules: 


Character set Code page 
Panel group XXX yyy 
Device aaa bbb 


Output conversion table = QUSRSYS/Qyyyaaabbb 
Input conversion table = QUSRSYS/Qbbbxxxyyy 


If the conversion table is not found, no conver- 
sion takes place. This conversion is done 
before any validity checking or inbound pro- 
cessing of a translation list. 


For a BASETYPE of GRAPHIC, CHRID=-PNLGRP 
is not allowed on this tag. The UIM does not 
perform character set and code page conver- 
sion on GRAPHIC fields containing DBCS 
data because there is no single-byte part of a 
GRAPHIC field. For GRAPHIC fields con- 
taining UCS-2 data, conversions will occur 
only between the specified UCS-2 CCSID and 
the device CCSID. 


When CHRID=PNLGRP is specified for a class 
with BASETYPE of IGC, the UIM converts only 
the single-byte portion of the field. No conver- 
sion is done on the DBCS portion of the field. 


SHIFT=NONE | UPPER 


If NONE is coded, no special keyboard shift is 
used for fields of this class. 


If UPPER is coded, the keyboard is shifted to 
uppercase for data entry for display input 
fields associated with variables of this class. 
The default keyboard shift is determined by 
the BASETYPE. For a summary of the BASETYPE 
and corresponding default, see Table A-4 on 
page A-18. 


CASE=MIXED | UPPER 


MIXED indicates that characters from any field 
of this class are preserved when assigned to 
the variable pool. 


UPPER indicates that lowercase characters (a 
through z) are uppercased before assignment 
to the pool. This translation takes place after 
any processing for the CHRID attribute on this 
tag and before any validity checking or 
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inbound processing of a translation list. Fora 
BASETYPE of GRAPHIC, CASE=UPPER is not 
allowed. The default case is determined by 
the BASETYPE. For a summary of the BASETYPE 
and corresponding default, see Table A-4 on 
page A-18. 


BLANKS=RESPECT | IGNORE 


RESPECT indicates that blanks in the input 
field are preserved when the value is assigned 
to the variable pool. 


IGNORE indicates that the value is left justi- 
fied when it is assigned to the variable pool. 
The default is determined by the BASETYPE. 
The processing to remove leading blanks 
takes place after any processing for the CHRID 
and CASE attributes on this tag, and before 
validity checking or inbound processing of a 
translation list. For a summary of the 
BASETYPE and corresponding default, see 
Table A-4 on page A-18. 


When BLANKS=IGNORE is specified for a 
BASETYPE of IGC, only leading SBCS blanks 
are removed from the field value. The pro- 
cessing to remove leading blanks stops at the 
first shift-out character in the field. 


SUBST=DISPLAY | QUOTED 


If DISPLAY is specified, the substitution 
values used on the CMD dialog command for 
this class of variables is the same as their dis- 
played values. 


If QUOTED is specified, the substitution 
values used on the CMD dialog command for 
this class of variables are enclosed in apostro- 
phes, and apostrophes within the values are 
doubled. Values translated with the trans- 
lation list (TL) tag are not quoted. 


BIDI=PNLGRP | LTR | RTL 


Sets the left-to-right or right-to-left orientation 
for variables of this class. This attribute is 
ignored when BIDI=NONE is specified on the 
PNLGRP tag. 


PNLGRP indicates that the parameter from 
the BIDI attribute on the PNLGRP tag should 
be used to set the orientation for variables of 
this class. 


LTR indicates that a left-to-right orientation 
should be used for variables of this class. 


RTL indicates that a right-to-left orientation 
should be used for variables of this class. 
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The orientation defaults to PNLGRP for 
classes with a BASETYPE of CHAR and IGC. 
Orientation defaults to LTR for classes with a 
BASETYPE of NAME, OBJNAME, BIN, 
PACKED, ZONED, DATE, TIME, and 
ACTION. 


The cursor direction is reversed for any input 
field which has an orientation opposite the 
panel's orientation. The cursor direction can 
be changed later when the CONTXTREV attribute 
of this tag is processed. 


CONTXTREV=NO | YES 


Specifies that a context-sensitive reversal is 
performed for bidirectional variables of this 
class. This attribute is ignored when 
BIDI=NONE is specified on the PNLGRP tag. 


For CONTXTREV=NO, when the orientation of a 
variable does not match the orientation of the 
panel group, the value for each display line of 
the variable is reversed before it is displayed. 
On entry, the contents of each display line of 
a field that has an orientation opposite to the 
panel is also reversed before it is moved from 
the display field to the variable pool. NO is 
the default. 


For CONTXTREV=YES, the contents of dialog 
variables are checked to determine the ulti- 
mate display orientation of the variable. The 
dialog variable value is checked before it is 
displayed. If the dialog variable is used in an 
input field, the value is checked again before 
the input value is copied to the variable pool. 
A description of the checking follows: 


e When BIDI=LTR is specified on the 
PNLGRP tag, 


— The dialog variable is inverted if and 
only if the dialog variable value con- 
tains at least one Arabic or one 
Hebrew alphabetic character, or if it 
contains no Latin characters and 
BIDI=RTL is specified on the CLASS 
tag. 


e When BIDI=RTL is specified on the 
PNLGRP tag, 


— The dialog variable is inverted if and 
only if the dialog variable value does 
not contain any Arabic or Hebrew 
alphabetic characters, and if either it 
contains Latin characters or BIDI=LTR 
is specified on the CLASS tag. 
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The Arabic and Hebrew code pages used to 
determine if the variable must have its display 
orientation flipped are described as follows: 


e For code page 420 


— The following hex values represent 
Arabic characters: 42 through 49, 51, 
52, 55 through 59, 62 through 69, 70 
through 79, 80, 8A through 8F, 90, 9A 
through 9F, AO, AA through AF, BO 
through B5, B8 through BF, CB, CD, 
CF, DO, and DA through DE. 


— The following hex values represent 
Latin characters: 6F, 81 through 89, 
91 through 99, A2 through AQ, C1 
through C9, D1 through D9, DF, E2 
through EB, ED, EE, EF, FO through 
F9, and FB through FE. 


— The remaining characters are not con- 
sidered to be Arabic and Latin. 


e For code page 424 


— The following hex values represent 
Hebrew characters: 41 through 49, 51 
through 59, 62 through 69, and 71. 


— The following hex values represent 
Latin characters: 81 through 89, 91 
through 99, A2 through AQ, C1 
through C9, D1 through D9, E2 
through E9, and FO through F9. 


— The remaining characters are not con- 
sidered to be Hebrew and Latin. 


For a CONTXTREV=YES input field, the initial 
cursor direction is determined the same way 
as for a CONTXTREV=NO input field. Then it is 
further processed and redetermined, based on 
the results of the following content inversion: 


¢ BIDI=LTR is specified on the PNLGRP 
tag: 
— When BIDI=LTR is specified on the 
CLASS tag: 


- The cursor direction is inverted if 
and only if the content of the 
dialog variable is inverted. 


— When BIDI=RTL is specified on the 
CLASS tag: 


- The cursor direction is inverted if 
and only if the content of the 
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dialog variable is not inverted and — When BIDI=RTL is specified on the 
if it contains at least one Latin CLASS tag: 

alphabetic character. (This pre- 
vents the inversion of the cursor 
direction in an empty field.) 


- The cursor direction is inverted if 
and only if the content is inverted 
and if the variable contains at 


¢ BIDI=RTL is specified on the PNLGRP least one Latin alphabetic char- 
tag: acter. (This prevents the inver- 
— When BIDI=LTR is specified on the sion of the cursor direction in an 
CLASS tag: empty field.) 
- The cursor direction is inverted if For a detailed summary of how 
and only if the content of the CONTXTREV=YES works for various fields and 


dialog variable is not inverted. panels, see the following decision tree. 
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No Are Any 
Arabic or Hebrew Ll 
Characters Found? 
Are Any Latin 
Characters 
Found? 
No | Yes 
Vv 
PNLGRP PNLGRP PNLGRP 
BIDI attribute BIDI attribute BIDI attribute 
| LTR | | 
a LTR 
RTL 
CLASS CLASS 
BIDI attribute BIDI attribute 
Result Result 
3 2 
RTL LTR RTL LTR y v 
Result Result 
4 1 
Result Result 
2 1 
Vv Vv 
Result Result 
4 3 
Result 1: Result 2: Result 3: Result 4: 
Right-to-left Right-to-left Left-to-right Left-to right 
cursor motion. cursor motion. cursor motion. cursor motion. 
Invert value Invert value 
of dialog of dialog 
variable. variable. 


RV2WO060-0 


NBRSHAPE=PNLGRP | ARABIC | HINDI 
Controls the display shape of application- 


When HINDI is specified, the translation of 
digits is performed with a set of two translation 


generated numbers for bidirectional variables 
of this class. This attribute is ignored when 
BIDI=NONE is specified on the PNLGRP tag, 
or when any code page other than 420 
(Arabic) is used by the display device. 


When PNLGRP is specified, the parameter 
from the NBRSHAPE attribute on the PNLGRP 
tag should be used for variables of this class. 
PNLGRP is the default. 


When ARABIC is specified, the normal digits 
X'FO' through X'F9' are used for numbers. 
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tables defined for each national language. 
The first table is used for output operations, 
and the second table is used for input oper- 
ations. 


The NBRSHAPE attribute allows the application 
program to not know the actual code points 
used to display the numeric digits. 


SYMSWAP=NO | YES 


Controls the exchange of symmetric charac- 
ters for bidirectional variables of this class. 


This attribute is ignored when BIDI=NONE is 
specified on the PNLGRP tag. An example of 
two pairs of symmetric characters are: 

‘(' with ')' 

‘<' with '>' 
When YES is specified, the symmetric char- 
acter exchange is performed for both input 
and output operations on any field displayed 


with a right-to-left orientation. The situations 
where this can occur are: 


¢ CONTXTREV=NO is specified on this tag for 
a variable that has a right-to-left orien- 
tation. 


¢ CONTXTREV=YES is specified on this tag for 
a variable that has a right-to-left orien- 
tation, and the contents of the field causes 
the resulting field orientation to stay right- 
to-left. 


¢ CONTXTREV=YES is specified on this tag for 
a variable that has a left-to-right orien- 
tation, and the contents of the field causes 
the resulting field orientation to change to 
right-to-left. 


When SYMSWAP=NO is specified, symmetric 
character exchanges are not performed. NO 
is the default. 
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The complete list of symmetric characters for 
Hebrew (code page 424) is: 


( with ) Right and left parentheses, 4D 
with 5D 

{ with } Right and left braces, CO with DO 

[ with ] Right and left square brackets, 
BA with BB 

< with > Less than and greater than signs, 
4C with 6E 

< with > Double less than and double 
greater than signs, 8A with 8B 


The complete list of symmetric characters for 
Arabic (code page 420) is: 


( with ) Right and left parentheses, 4D 
with 5D 

< with > Less than and greater than signs, 
4C with 6E 


All symmetric characters generated by the 
UIM are processed as if SYMSWAP=YES is 
specified. At this time, the symmetric charac- 
ters include: 


> Greater than symbol. Used to mark menu 
options and used in the command line 
prompt 


() Right and left parentheses symbols. Used 
around an empty list message. 
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Example: Class Definitions 


UIM Source 


Class of options whose only legal values 
are Y, N, and blank. 
These values are translated to an 
internal form. 
:class name=option 
basetype='bin 15' 
case=upper width=1. 
:tl msgid=MMM1234. 
:ti value=1.Y 
:ti value=2.N 
:ti value=3. 
set]. 
seclass. 
x 
-* class of object names or the special 
-* value «all 
:class name=object 
basetype='objname 10 generic’. 


+ + F 


:tl. 

:ti value='"*ALL"'.*ALL 

setl. 

:eclass. 

x 

-* Class of options from 1-5 or 7-9, 

-* ina field of width 1. 

:class name=listoption 
basetype='bin 15' width=1. 

:check range='1 5' range='7 9'. 

seclass. 


Display Forms of Numeric Values 


Numbers are usually displayed without leading 
zeros. If the absolute value of the number is less 
than one, a leading zero before the decimal point 
is supplied or suppressed, based on the 
QDECFMT system value. Numbers are signed 
only if the number is negative. A decimal point is 
displayed only if there are fractional digits. The 
decimal point character used is the one defined by 
the system value QDECFMT. Numbers are dis- 
played preserving all fraction digits. 


If a value is too large to fit in the display field on 


output, the field is filled with plus signs. If a field 
consists entirely of plus signs on entry, no validity 
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checks are performed on the field and the value of 
the variable in the variable pool is left unchanged. 


Numeric literals must be of the form: 


+- 
>> — ra | >< 


: : digit 


or 
i 
>> = ie digit >< 
digit 


A comma may be used in place of a period for 
decimal point on input. If conversion to the 
internal form loses significant digits, the field is 
considered in error and the UIM displays an error 
message to the user without altering the contents 
of the variable pool. All nonzero digits after the 
decimal point are considered significant, and 
attempts to truncate result in an error. Leading 
zeros before the decimal point and trailing zeros 
after the decimal point are not considered signif- 
icant. If a sign is not supplied, the value is 
assumed to be positive. 


Binary values can also be translated to character 
strings on output and from character strings on 
entry. In this case, the value specified for the 
WIDTH attribute on this tag must allow for the width 
of the translated character string specified on the 
translation list item (Tl) tag. For more information 
on translation lists, see “TL (Translation List)” on 
page A-159 and “TI (Translation List Item)” on 
page A-158. 


Any variable with a BASETYPE of ACTION is 
handled with editing rules for a numeric value, 
except that a zero value is displayed as blanks, 
and a zero input value is not valid. Plus signs are 
not allowed on entry. Translation lists and validity 
check processing are not allowed for variables 
whose BASETYPE is ACTION. 


Some examples of the display for numeric values 
are shown in the following table. 


CLASS Tag 


Internal Displayed Notes 

BASETYPE WIDTH Value Value 

BIN 15 1 1 1 

BIN 15 1 -1 + (Value too large to display) 
BIN 15 5 1 1 

BIN 15 5 -1 -1 

BIN 15 5 -3456 -3456 

BIN 15 5 -32768 ++tt+ (Value too large to display) 
BIN 16 5 65535 65535 

BIN 31 10 2147483645 2147483645 

BIN 31 9 2147483645 tttt+++++ (Value too large to display) 
BIN 32 10 4294967295 4294967295 

BIN 32 9 4294967295 ttttt4+4+ (Value too large to display) 
PACKED 2 2 45 ~45 Calculated field width is 5 
PACKED 2 2 -.45 -.45 Calculated field width is 5 
PACKED 5 2 000.45 0.45 Calculated field width is 7 
PACKED 5 2 -000.45 -0.45 Calculated field width is 7 
PACKED 5 2 8 000.45 0.45 

PACKED 5 2 8 -000.45 -0.45 

PACKED 5 2 8 123.45 123.45 

PACKED 5 2 8 -123.45 -123.45 

PACKED 5 2 4 -123.45 t+4+t+ (Value too large to display) 
PACKED 5 2 4 003.45 3.45 

PACKED 5 0 00001 1 Calculated field width is 6 
PACKED 5 0 00000 0 Calculated field width is 6 
PACKED 5 0 -00000 0 Calculated field width is 6 
PACKED 5 0 -00001 -1 Calculated field width is 6 


Display Forms of Character, Date, 
and Time Values 


Character values are displayed as they appear 
from the variable pool, padding with nulls on the 
right as necessary. If the value entered into the 
input field is not translated using a translation list, 
an error is reported to the user and the dialog var- 
iable is not updated if the value is longer than the 
BASETYPE of the variable after trailing blanks are 
removed. Only trailing SBCS blanks are removed; 
DBCS blanks are considered significant. 


Dates are always displayed in the form specified 
by the date format and date separator of the 
current job. When a date is entered by a user, it 


must be in the format specified by the date format 
of the current job, but the separator characters 
specified by the date separator of the current job 
are optional. Because the date formats do not 
allow the entry of the century digit, it is assumed 
to be 0 if the year number is greater than 40. If 
the year number is less than or equal to 40, the 
century digit is assumed to be 1. 


Times are always displayed in a 24-hour time 
format, with the time separator as specified by the 
time separator of the current job. The separator 
characters specified by the time separator of the 
current job are optional. If a time is entered 
without a time separator, either four or six digits 
must be supplied. 
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CMDLINE Tag 


CMDLINE (Command Line) 


p>>—: CMDLINE—SIZE= ea 
LONG 


LNAME=conmand: l iecnones 


>< 
Leanebriee ion- foxee 


The command line (CMDLINE) tag specifies that 
the panel has a command line and provides addi- 
tional command line information. This tag is 
allowed only for display panels. A command line 
may appear on any panel and may be inde- 
pendent of all areas on the panel, or it may be 
associated with an action list or menu area on the 
panel. 


Only system commands can be entered on the 
command line, unless the panel contains a menu 
area or an action list area. If the panel contains a 
menu area, the user enters either a menu option 
or a command on the command line. For an 
action list, the user enters a string that is either 
run aS a command or acts as parameter informa- 
tion for action list processing. 


This tag must be the final tag in the panel, and is 
placed just before the end of the display panel. 
The CMDLINE tag and the option line (OPTLINE) 
tag are mutually exclusive. 


Required Attribute 


SIZE=SHORT | LONG 
A SHORT command line takes up only one 
line of the display and fills up that line. 


A LONG command line takes up two lines on 
the display. 


SIZE=SHORT must be specified if a panel 
width other than 80 bytes (or 132 bytes) is 
specified on the display panel (PANEL) tag. 
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SIZE=LONG is valid only for a 27-row by 
132-byte panel or a 24-row by 80-byte panel. 


When BIDI=RTL is specified on the panel 
group (PNLGRP) tag, all SIZE=LONG 
command lines are automatically formatted by 
the compiler to a one-line command line with 
a blank line separator between the command 
line and the function key area. 


Optional Attribute 


NAME=commanda-line-name 
The name associated with the command line. 
This name can be used later with the Add 
Pop-Up Window (QUIADDPW) API to position 
a window near the command line. 


For more information on the rules for naming, 
see “Name Syntax” on page A-4. 


Optional Text 


instruction-text 
The text appearing as instructions for the 
command line. The text is an implied para- 
graph. 


When the display is formatted, any text that 
does not fit on one display line is formatted on 
multiple lines as necessary and indented two 
display positions. The text can be a maximum 
of 255 characters and can only contain the 
reverse text (RT) tag. If no text is provided, 
no instruction line is displayed above the 
command line. 


COND Tag 


COND (Condition Definition) 


>>— : COND—NAME=condition-name—EXPR='conditional-expression' 


> 


Leval- 
EVAL=——ALWAYS 
Lowce—! 


>< 


The condition definition (COND) tag defines a con- 
dition that must be true if certain processing is to 
take place. Other tags may refer to this condition, 
which is evaluated before a panel is displayed. If 
the condition is true, the action or formatting spec- 
ified by the referring tag is performed. 


Required Attributes 


NAME=condition-name 
The name of the condition specified in the 
expression. The name must be unique within 
the panel group. 


For more information on the rules for naming, 
see “Name Syntax” on page A-4. 


EXPR=' conditional-expression'. 
A conditional expression is a true or false 
expression in the following form: 


*AND 
“oR | 
>> ! 4 A | >< 


(4) 
*NOT (A) 


where A is an operand which can be one of 
the following: 


e Aconditional expression 

e Acomparison between a dialog variable 
and a literal value 

e Acomparison between two dialog vari- 
ables 

¢ A built-in function 


When operand A is a conditional expression, 
the “AND and *OR logic becomes more 
complex. 


The logical OR character (|) can be used in 
place of “OR, the ampersand character (&) 
can be used in place of *AND, and the logical 
NOT character (=) can be used in place of 
“NOT. Since the logical OR and logical NOT 
characters are not in the invariant character 
set, their use is not recommended. For code 


page 00037, the common USA code page, the 
hexadecimal value of the logical OR character 
is X'4F', and the hexadecimal value of the 
logical NOT character is X'5F'. The UIM 
compiler uses these hexadecimal values 
regardless of the code page of the source. 


When operand A is a comparison between a 
dialog variable and a literal value, or between 
two dialog variables, it must be in the fol- 
lowing form: 


pe av oeag var vaya fame > 

Teeraivelie | 

»>——relational-operator > 

a ee >< 
tlendivaiie= 


The relational operator may be specified as =, 
n=, >, <, >=, Or <=, if the code page of the 
source maps the not character (7) to X'5F'. 
Otherwise, it is suggested that the special 
values *EQ, *NE, *GT, *LT, *“GE, or *LE be 
used, respectively for the relational operator. 


Comparisons may take place only between 
items of matching BASETYPE and precision as 
defined on the class definition (CLASS) tag. 
Comparisons between two literals are not 
allowed. 


Character string literals must be enclosed in 
double quotation marks (")._ The UIM does 
not automatically uppercase character strings. 


Hexadecimal strings are allowed as character 
strings. Hexadecimal strings cannot be used 
for comparison with dialog variables defined 
with a BASETYPE of GRAPHIC on the CLASS 
tag. For more information about specifying 
hexadecimal strings, see “Hexadecimal 
Literals” on page A-6. 


For a comparison between a dialog variable 
whose BASETYPE is GRAPHIC (as defined on 
the CLASS tag) and a literal, a double-byte 

character set (DBCS) graphic literal must be 
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COND Tag 


used. For more information about specifying 
a DBCS graphic literal, see “DBCS Graphic 
Literals” on page A-6. 


Numeric literals must be of the form: 


+- 
>> = L gigit— | >< 


: : digit 


or 
>> = - = 5 ! digit >< 
digit 


where dis a digit from 0 through 9. 


This attribute is repeatable so that an 
expression can span several lines. 


When operand A is a built-in function, it can 
be used as follows: 


CHKOBJ 
Evaluates to true if the object is found on 
the system and the current job possesses 
at least the level of authorization to the 
object specified by the authorities. Argu- 
ments must be character strings enclosed 
in double quotation marks ("). The object 
name follows OS/400 object naming con- 
ventions. The object type is any of the 
allowable object types for the DSPOBJD 
command and the authorities must be a 
single value or a list of authorizations to 
be checked for. The values of these 
authorizations are separated by blanks. 
The following syntax diagram illustrates 
the authorities and how to use them: 


A-28 Application Display Programming V4R1 


>>—CHKOBJ (—70bj-name~—7—,—"obj- type "—__p 
'—"obj-name" 


> )—~< 
eo * CHANGE: : 

*ALL 

*USE 

* EXCLUDE 

* AUTLMGT 


Note: 
' Each value can be used only once, with 
a maximum of 7. 


If no authorities are specified, no authori- 
zation check is performed and the function 
becomes an existence check. 


CHKUSRCLS 
The user class argument specified for the 
function is compared to the user class 
parameter from the user profile of the 
current job. The function evaluates to true 
if the user profile has the same or greater 
value than the function argument. The 
function argument must be enclosed in 
double quotation marks ("). 


The following syntax diagram illustrates 
the valid argument values for the user 


class: 
>>—CHKUSRCLS (7—* SECOFR-—_) ————>~« 
* SECADM 
*PGMR 
*SYSOPR 
*USER 


CHKOBJ("OBJECT", "*FILE", "*USE") 


CHKOBJ ("PANELGRP", "*PNLGRP") 
*AND CHKUSRCLS ("*PGMR") 


CHKOBJ ("DOCUMENT","*DOC","*READ *UPD") 


*OR CHKUSRCLS("*SYSOPR") 
*NOT (CHKOBJ ("PROGRAM" ,'"*PGM") ) 


Optional Attribute 
EVAL=ALWAYS | ONCE 


Indicates whether or not the expression speci- 
fied on the EXPR attribute of this tag must be 


evaluated every time the condition is referred 
to, or if it needs to be evaluated only once. 


If EVAL=ALWAYS is used, the expression is 
evaluated to determine a new truth value 
every time the condition is referred to. All 
EVAL=ALWAYS conditions in a panel group or 
menu are evaluated each time a panel or 
menu is displayed. ALWAYS is the default. 


If EVAL=ONCE is specified, the expression is 
evaluated only once for every open application 
that uses the panel group. The UIM only 
evaluates the expression for a condition of this 
type the first time the condition is referred to. 
Every reference after the first one uses the 
same truth value determined by the first refer- 
ence. ONCE may be specified to improve 
performance for conditions that do not change 
while the application is open, particularly if the 
expression requires the evaluation of a func- 
tion (like CHKOBuJ) that may be costly. 


Example: Conditioning an Option 


The following example shows how the COND tag 
might be used to condition menu items. The first 
condition uses a complex expression which is split 
onto two source lines. The second condition 
checks for the application user's authority to use a 
menu on the system, and the third condition 
checks for the user class of the application user. 


COND Tag 


UIM Source 


:cond name=a 
expr='(varl = 100 *AND var2 > 0)' 
expr='*OR *NOT(var3 = 0)'. 

:cond name=b 


expr='chkobj("MENU2","*MENU","*READ, *UPD")'. 


:cond name=c 
expr='chkusrcls("*PGMR")'. 


:menui 
cond=a 
help='optionl/help' 
action='CMD CALL PGMO1' 
option=1.Run report 
:menui 
cond=b 
help='option2/help' 
action='MENU MENU2' 
option=2.Administration 
:menui 
cond=c 
help='option30/help' 
action='MENU UTIL' 
option=30.Utilities 
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COPYR Tag 


COPYR (Copyright) 


pe—:COPYR—.—notice-text 


>< 


The copyright (COPYR) tag provides a way to 
present a copyright notice. Only one COPYR tag 
is allowed. The copyright notice is displayed in 
the message area of the first panel displayed after 
the panel group is opened. This tag must be 
coded immediately after the panel group 
(PNLGRP) tag. 
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Required Text 


notice-text 
The text of the copyright notice that is dis- 
played. The text must be between 1 to 76 
characters. 


DATA Tag 


DATA (Data Presentation Area) 


;—— Syntax for Display Panels 


p>>— : DATA—DEPTH= area-depth 


i; a _] : 
‘x! HELP=he lp-module-name L SPACE 
BOTSEP=——NONE 


The data presentation area (DATA) tag describes 
a data presentation area in a panel. This tag is 
allowed for display panels and print panels. This 
area can be used for data entry items or output 
data items, or any combination of the two. 


Other tags can be nested within the DATA tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 


RULE 
> A > 
aT Cv) Conve 
SCROLL= l ves LAYOUT= b2 MAXHEAD= 1 
HORIZ 2 
3 
A 
ag :EDATA. >< 
a SPACE coMPAcT_ Lsoreuseitiee 
BODY SEP= INDENT: 
BOTH 
NONE 
;—— Syntax for Print Panels 
>>—:DATA > 
Tpseaces | | al 
BOTSEP= vone— LAYOUT= b2 MAXHEAD= 1 
RULE HORIZ 2 
3 
A 
> > 
I SPACE Lcompact— | aoe | Parente: 
BODY SEP= INDENT: TYPE= PROLOG 
BOTH 
NONE 
>—:EDATA. >< 


(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 
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DATA Tag 


Table A-5. Tags Allowed Between the DATA and 
EDATA Tags 


Tag Name Order Use Page 


TOPINST 1 D A-161 
(Top instruction 
line) 


DATACOL 2 B A-39 
(Data column) 


DATAGRP 3 B A-40 
(Data item group) 


DATAI 3 B A-42 
(Data item) 


DATASLT 3 D A-51 
(Data selection 
field) 


BOTINST 4 D A-10 
(Bottom instruc- 
tion line) 


Required Attribute 
DEPTH=area-depth | '*' 


The depth of the area in lines, including sepa- 


rators if any are specified. This attribute is 


required for display panels but is not allowed 
for print panels. If '*' is specified, the space 
remaining on the display after all else is allo- 
cated is given to this area. Only one area in 


the panel may have '*' coded. 


Optional Attributes 


HELP=help-module-name 
Identifies online information explaining all 
items in the area. This attribute is allowed 
only for display panels. The help module 


name may be a name imported from another 


panel group, but must follow the rules for 
names outlined earlier in this chapter. For 


more information on the rules for naming, see 


“Name Syntax” on page A-4. 


A single help module name must be associ- 
ated with every item in the area. If the HELP 


attribute is specified on the DATA tag, the 
help applies to all groups and items in the 


area, and the HELP attribute is not allowed on 


any data group (DATAGRP), data item 


(DATAI), data selection field (DATASLT), and 
data selection field choice (DATASLTC) tags 


in the area. 
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If no HELP attribute is specified on the DATA 
tag, a help module name must be associated 
with each item in the area by specifying the 
HELP attribute on the DATAGRP tags or the 
DATAI and DATASLT tags. 


To provide the user with easy access to the 
online information for a data area with the 
LAYOUT=HORIZ attribute specified on this tag, 
specify the HELP attribute on the DATA tag 
instead of the HELP attribute on the individual 
DATAI tags. 


BOTSEP=SPACE | NONE | RULE 


Defines the bottom separator for the data 
presentation area. If SPACE is specified, a 
line of spaces is used. SPACE is the default. 


NONE indicates that no separator line exists. 


RULE indicates that a line of underscored 
spaces is used. 


SCROLL=NO | YES 


Specifies whether or not the area is scrollable. 
This attribute is allowed only for display 
panels. NO indicates that the area is not 
scrollable. NO is the default. 


YES indicates that the data presentation area 
is scrollable. SCROLL=YES is not allowed 
when LAYOUT=HORIZ is specified. A line of 
spaces is used by the UIM to provide a line 
for the scroll information. If BOTSEP=SPACE, 
only one line of spaces is used unless this 
area also contains bottom instructions. 


LAYOUT=1 | 2 | HORIZ 


Indicates either the number of layout columns 
for a vertically formatted area or that a hori- 
zontal format should be used. 


For LAYOUT=1, there is only one column of 
data items. For panels with WIDTH=80 bytes 
on the panel definition (PANEL) tag, the single 
column of data items is in positions 2 through 
79. For panels with WIDTH=132, the single 
column of data items is in positions 2 through 
131. 


For LAYOUT=2, two layout columns of equal 
width are used for data items. The data items 
specified within the area appear in order, from 
top to bottom within a layout column and from 
left to right between layout columns. For 
panels with WIDTH=80, the two layout columns 
are in positions 2 through 38 and 43 through 
79. For panels with WIDTH=132, the two layout 


columns of data items are in positions 2 
through 64 and 69 through 131. 


For LAYOUT=HORIZ, the data fields are listed 
horizontally across the width of the panel, with 
five spaces between items. This layout is 
useful if only two or three short values are 
necessary. It should be limited to a single 
display line, because the UIM does not verti- 
cally align items appearing on different lines 
within the area. 


MAXHEAD=0 | 1 | 2|3| 4 


The maximum number of lines that can be 
used for column headings. The column 
headings are specified using the data column 
(DATACOL) tag. From zero to four lines can 
be specified. Zero is the default, meaning that 
no column headings are allowed. Only 
MAXHEAD=0 is valid for a data presentation area 
with a horizontal layout, because column 
headings are not allowed in horizontal presen- 
tation. For more information on column 
headings, see “DATACOL (Data Column)” on 
page A-39. 


When column headings are used, you may 
want to provide expansion space for national 
language translation by specifying a MAXHEAD 
value larger than the number of heading lines 
required. If this is not done, expansion space 
must be provided within the column widths 
determined by the DATACOL tag. 


BODYSEP=SPACE | INDENT | BOTH | NONE 


The type of visual separation distinguishing 
the body of the area from other elements on 
the display, particularly any top and bottom 
instruction lines within the area. 


SPACE leaves a blank line after the last top 
instruction line and before the first bottom 
instruction line. Items in the body of the area 
begin in the leftmost position of the layout 
column. They are not indented with respect to 
instruction lines. If the area contains no top or 
bottom instruction lines, no blank lines are 
reserved before or after the area body. 


INDENT is used to indent items in the body of 
the area by two bytes from the leftmost posi- 
tion in the layout column where the instruction 
lines begin. If the area contains top or bottom 
instruction lines, no blank line is reserved 
between the instructions and the area body 


DATA Tag 


except if the area is scrollable. If the area is 
scrollable, a blank line is reserved to provide a 
line for the scroll information. 


BOTH leaves a blank line after the last top 
instruction line and before the first bottom 
instruction line, and also indents items in the 
body of the area by two bytes from the left- 
most position in the layout column where the 
instruction lines begin. If the area contains no 
top or bottom instruction lines, no blank lines 
are reserved before or after the area body. 


NONE does not leave a blank line between 
the instruction line and the body, and does not 
indent the body with respect to the layout 
column except if the area is scrollable. If the 
area is scrollable, a blank line is reserved to 
provide a line for the scroll information. 


COMPACT 
If COMPACT is specified, no blank lines are left 
between column headings and all items and 
outer groups in the area. If COMPACT is not 
specified, a blank line appears after the area 
column headings and between all items and 
outer groups. 


TYPE=NORMAL | PROLOG 
Indicates whether or not this data area is a 
prolog area. The prolog area is printed only 
once after the title line on the first page. This 
attribute is allowed only for the print head 
panel (PRTHEAD) tag. NORMAL is the 
default value. 


Optional Text 


area-title 
The title of the area. If no text is specified, no 
title line is allocated to the area. The text 
must appear on the same or next line as the 
tag, can contain only the reverse text (RT) 
tag, and is a maximum of 55 characters long. 


Print Formatting Considerations 


Printed data areas are formatted similarly to data 
areas that are displayed, with the following 
exceptions: 


e When printing, there is a minimum of two lines 
of data entries on a page besides the data 
group headings and the data column 
headings. 
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DATA Tag 


e If two lines of data entries do not fit ona 
page, a page eject occurs and the data 
entries are printed on the next page. 


For formatting of data areas with LAYOUT=2, the 
UIM balances the data entries across the page 
and ignores keep processing. 


This format may not look good in some cases, but 
LAYOUT=2 data areas should only be used on small 
data areas or when the user is not concerned 
about keep processing. 


If there are data column headings, they are 
repeated on each page if the data area is con- 
tinued onto another page. 


Example 1: Data Entry Panel 


The following example shows a sample data entry 
panel. The panel has 5 prompts; 4 prompts have 
defaults supplied to the calling program by previ- 
ously setting the dialog variables for the function. 


UIM Source 


:panel name=entryl 

help=hentry1 

topsep=space 

keyl=keys 

.Sample Entry Panel 
:data depth='*' 

maxhead=2. 

:topinst.Type choices, press Enter: 
:datacol width=20.Item 
:datacol width=10.Choice 
:datacol width='*'.'Possible Choices' 
:datai usage=inout 

help=hfname 

var=fname.File name 
:datac.Name of document to be printed 
:datai usage=inout 

help=hstyle 

var=prtstyle.Type style for printing 
:datac.1=Prestige Elite (12 pitch) 
:datac.2=Courier (10 pitch) 
:datac.3=Essay Standard (proportional) 
:datac.4=Essay Bold (proportional) 
:datai usage=inout 

help=hmargn 

var=margin.Left margin 
:datac.Number of spaces from the left 
edge of the paper (1-20) 
:datai usage=inout 

help=hcopy 

var=copies.Copies 
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:datac.Number of copies (1-99) 
:datai usage=inout 

help=hdup1x 

var=duplex.Duplex 
:datac.1=Yes (Print both sides of paper) 
:datac.2=No (Print one side only) 
:edata. 
:epanel. 


Results 


[ | 
Sample Entry Panel 


Type choices, press Enter: 


Item Choice Possible Choices 


File name .. 1... Name of document to be printed 

Type style for 
printing... .. 1 1=Prestige Elite (12 pitch) 

a 2=Courier (10 pitch) 

3=Essay Standard (proportional) 

4=Essay Bold (proportional) 


Left margin .... 6 Number of spaces from the left edge of 
Pas the paper (1-20) 


Copies. ...... 1 Number of copies (1-99) 


1=Yes (Print both sides of paper) 
2=No (Print one side only 


DUP EX! oe Seater. 1 


F3=Exit F12=Cancel 


E J 


Example 2: Two-Column Format 
in a Data Entry Panel 


The following example shows a data area using 
two-column format containing output items, and a 
form of data entry field that has no prompt. 


UIM Source 


:panel name=panel x 
hel p=hel px 
topsep=space 
keyl=keys 
-Another Sample Panel 
:data depth=14 layout=2. 
:datacol width='24', 
:datacol width='*'. 
:datagrp compact.Compact data group 
:datai usage=out 
help=hvarl 
var=varl.First element 
:datai usage=out 
help=hvar2 
var=var2.Second element 
:edatagrp. 
:datai usage=out 
hel p=hvar3 
var=var3.Third element 
:datagrp grpsep=qindent 
compact. 
:datai usage=out 


help=hvar4 

var=var4.Fourth element 
:datai usage=out 

help=hvar5 

var=var5.Fifth element 
:datai usage=out 


help=hvar6 
var=var6.Sixth element 
:edatagrp. 


:datagrp compact.Another compact group 
:datai usage=out 
help=hvar7 
var=var7.Seventh element 
:datai usage=out 
help=hvar8 
var=var8.Eighth element 
:datai usage=out 


help=hvar9 
var=var9.Ninth element 
:edatagrp. 


:datagrp help=hvar1012 
grpsep=none compact. 
:datai usage=out 
var=varl0.Tenth element 
:datai usage=out 
var=varll cond=cond1ll. 
:datai usage=out 
var=varl2 cond=condl2. 
:edatagrp. 
:datagrp grpsep=none 
compact. 
:datai usage=out 
help=hvar13 
var=varl3.Thirteenth element 
:datai usage=out 
help=hvar14 
var=varl4.Fourteenth element 
:datai usage=out 
help=hvar15 
var=varl5.Fifteenth element 
:edatagrp. 
:edata. 
:data depth=3 
bodysep=none. 
:datacol width=0. 
:datacol width='*'. 
:datagrp.Sixteenth element 
:datai usage=inout 


help=hvarx 
var=varx. 
:edatagrp. 
:edata. 
:epanel. 
Results 


DATA Tag 


[ | 
Another Sample Panel 


Compact data group: Another compact group: 
First element . . . : — XXXXXXXXXX Seventh element . . : — XXXXXXXX 
Second element . . . : — XXXXXXXXXX Eighth element . . . : — XXXXXXXX 
Ninth element . . . : — XXXX 
Third element . . . . : — XXXXXXXX 
Tenth element .. . . : — XXXXXXXX 
Fourth element . . . . : — XXXXXXXX XXXXXXXX 
Fifth element ...: XXXXXXXX XXXXXXXX 
Sixth element ...: XXXXXXXX 
Thirteenth element . . : — XXXXXXXX 
Fourteenth element . . : — XXXXXXXX 
Fifteenth element . . : — XXXXXXXX 


Sixteenth element: 


F3=Exit F12=Cancel 


Example 3: Two Presentation 
Areas for Data Items 


The following two examples show three data 
areas, which are initialized from the dialog vari- 
ables in the variable pool. The first two areas are 
aligned horizontally, and the third area is for- 
matted vertically. 


UIM Source 


:panel name=xmp3 
keyl=x1 
hel p=hxmp3 
.Data Item Extenders 

:data depth=2 
layout=horiz 
botsep=space. 

:datai usage=out 
var=date 
help=hdatetime.Date and time 

:dataix usage=out 
var=time 
newl ine=no 
itemsep=1. 

:edata. 

:data depth=2 
layout=horiz 
botsep=space. 

:datai usage=out 
var=jobname 
help=hdatetime.Job name 

:dataix usage=out 
var=user 
newl ine=no 
itemsep=1. 

:dataix usage=out 
var=jobnbr 
newline=no itemsep=1. 

:edata. 

:data depth='*' 
layout=1 
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DATA Tag 


botsep=space 
compact. 
:datacol width=0. 
:datacol width='*'. 
:datagrp grpsep=indent 
help=dependptfs 
compact.Dependent PTFs 
:datai usage=out 
var=ptfl. 
:dataix usage=out 
var=ptf2. 
:dataix usage=out 
var=ptf3. 
:dataix usage=out 
var=ptf4 
newline=yes. 
:dataix usage=out 
var=ptf5. 
:edatagrp. 
:edata. 
:epanel. 


Results 


Data Item Extenders 
Date and time: 12/31/99 12:59:59 
Job name: DSPQ1 QSECOFR 012345 
Dependent PTFs: 


XXXXXXXXXXXXXXX — XXXXXXXXXXXXXXX_ —XXXXXXXXXXXXXXX 
XXXXXXXXXXXXXXX_— XXXXXXXXXXXXXXX 


F3=Exit F12=Cancel 


Example 4: Data Presentation 


Area with a Menu Area 


UIM Source 


:panel name=xxx 
keyl=x1 
hel p=hxxx 
-Work with Files 
:data depth=2 
Jayout=horiz. 
:datai var=fname 
help='filename'.File 
:datai var=Iname 
help='libname'.Library 
:edata. 
smenu depth='*'. 


A-36 Application Display Programming V4R1 


:topinst.Select one of the following: 


smenui action='return 1' 
help='hoption1' 


option=1.Display file attributes 


smenui action='return 2' 
help='hoption2' 


option=2.Display file contents 


:menui action='return 3' 
help='hoption3' 
option=3.Change ownership 

:menui action='return4' 
help='hoption4' 


option=4.Change authorizations 


:menui action='return 5' 
help='hoption5' 
option=5.Destroy 

:menui action='return 6' 
help='hoption6' 
option=6.Backup to tape 

:emenu. 

:optline.Selection 

:epanel. 


Results 


Work with Files 
System: 
File:  MEM047123 Library: QGPL 


Select one of the following: 


. Display file attributes 
Display file contents 
Change ownership 

. Change authorizations 
Destroy 

Backup to tape 


anEwne 


Selection 


F3=Exit F12=Cancel 


XXXXXXXX 


; 


Example 5: Data Entry Panel 


with a Nested Data Group 


UIM Source 


:panel name=nestg 
help=helpn 
topsep=space 
keyl=keys 
.Nested Data Group 

:data depth='*' 
scroll=no. 

:topinst.Type choices, press Enter. 

:datacol width=40. 

:datacol width=10. 

:datacol width='*'. 

:datagrp compact 


grpsep=none. 
:datai usage=inout 

help=hjobq 

var=jobq.Place on job queue 
:datac.Y=Yes, N=No 
.* The following "datagrp" tag is 
.*needed to cause indentation for 
.* the "For choice Y=Yes" data group. 
:datagrp compact 

grpsep=indent. 
:datagrp compact 

grpsep=indent.For choice Y=Yes: 
:datai usage=inout 

hel p=hcmpmsg 

var=cmpmsg.Send completion message 
:datac.Y=Yes, N=No 
:edatagrp. 
:edatagrp. 


:edatagrp. 
:epanel. 


Results 


DATA Tag 


Nested Data Group 
Type choices, press Enter. 
Place job on job queue. ........ 


For choice Y=Yes: 
Send completion message ...... 


F3=Exit F12=Cancel 


Y=Yes, N=No 


Y=Yes, N=No 
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DATAC Tag 


DATAC (Data Item Choices) 


>> 


:DATAC 
Leuo eeeaiuieaevantabrecnane= 


>< 


peek force i aval 


The data item choices (DATAC) tag provides the 
text for the possible choices column of a data 
presentation area. This tag is allowed for display 
panels and print panels. It is not valid if only two 
data column (DATACOL) tags are specified for the 
area, or if LAYOUT=HORIZ is specified on the data 
presentation area (DATA) tag for the area. 


The DATAC tag must appear after the corre- 
sponding data item (DATAI) tag. More than one 
DATAC tag may be specified after the DATAI tag 
to provide several lines of text. If no DATAC tags 
are entered, no text exists in the possible choices 
column for the data item. 


Optional Attribute 


CHOICE=dialog-variable-name 
The name of a dialog variable containing the 
choices text to be displayed. The dialog vari- 
able must be defined with a width less than or 
equal to the width specified on the third 
DATACOL tag for the data area, the possible 
choices column. If the CHOICE attribute is 
used, no text-for-choices can be specified 
after the period of this tag. 
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Dialog variables must be defined with a 
BASETYPE of CHAR, IGC, or BIN on the class 
definition (CLASS) tag. 


The error state of the dialog variable is not 
used for determining the highlighting of the 
text. 


Special formatting for IGC. (The abbrevi- 
ation IGC is used in commands and keywords 
to represent double-byte character set func- 
tions.) When a dialog variable with a 
BASETYPE of IGC is specified on the CLASS 
tag, the UIM does special formatting. If the 
variable value begins with a shift-out character 
(X'0E'), the UIM shifts the value one byte to 
the left to preserve vertical alignment with 
data choices on other lines. 


Optional Text 


text-for-choices 
The text is an implied paragraph. Lines are 
formatted as necessary onto multiple lines 
within the column and indented two spaces 
from the beginning of the column. The text is 
a maximum of 255 characters and can only 
contain the reverse text (RT) tag. The text- 
for-choices is required unless the CHOICE attri- 
bute is specified on this tag. 


DATACOL Tag 


DATACOL (Data Column) 


pre sDAURCOL SIT 7 co aan Ween | 
ty! 


>< 


ey l enced ing. 


The data column (DATACOL) tag specifies the 
width of the item, choice, and possible choices 
columns, and can also provide column headings. 
This tag is allowed for display panels and print 
panels. It is not valid if LAYOUT=HORIZ is speci- 
fied for the data presentation area. It must appear 
after the data presentation area (DATA) tag for the 
area and before the first data item (DATAI), data 
selection field (DATASLT), or data group 
(DATAGRP) tag. 


Two or three DATACOL tags must be specified 
when the LAYOUT attribute of on the DATA tag 
specifies 1 or 2. If only two DATACOL tags are 
used, the area has no possible choices column 
and no data item choices (DATAC) tags are 
allowed in the area. If three DATACOL tags are 
specified, all three columns are allocated, 
including the possible choices column. 


Required Attribute 


WIDTH=column-width | '*' 
The width, in bytes, for the column. The width 
specified must be a positive integer, and the 
sum of the widths of the columns and separa- 
tors in the data presentation area must not 
exceed the width of the layout column deter- 
mined by the DATA tag. WIDTH=0 is allowed 
only for the first DATACOL tag; it formats the 
area without an item column for data item or 
data selection field prompt text. 


If '*' is coded, the remainder of the area 
width is used for the column. Only one 
DATACOL in the area may have '*' specified. 
A three-column separator is maintained 
between columns, except when WIDTH=0 is 
specified for the first DATACOL tag. In this 


case, the item column is not allocated and 
there is no separator in front of the choice 
column. 


The value for any data item may span 
columns, but must begin on the correct 
column boundary. The possible choices text 
for that item, assuming three DATACOL tags 
are specified, begins in the location assigned 
to the possible choices. This possible choices 
text may be on the same or next line as the 
data item field. 


Optional Text 


column-heading 
The column heading placed above the data 
items in the data area. If no column heading 
is specified, none is displayed. 


The text may appear on more than one line 
and can contain only the reverse text (RT) 
tag. Each word of the column heading is 
placed on a new line. If multiple words are 
necessary in a line of the column heading, 
they must be enclosed in apostrophes ('). 
Each word or quoted string must fit within the 
column width defined by the WIDTH attribute on 
this tag. The maximum number of words or 
quoted strings allowed is specified by the 
MAXHEAD attribute on the DATA tag. Column 
headings are not allowed if MAXHEAD=0 is used 
for the data area. 


The column headings are left-justified. If no 
column heading text is specified on any 
DATACOL tag for the area, no lines are 
reserved on the display for heading informa- 
tion. 
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DATAGRP Tag 


DATAGRP (Data Group) 


;—— Syntax for Display Panels 
>>—: DATAGRP > 
HELP Shetp moda tesname= ENAME-dadasoroup name 
| iia | l= = 
I INDENT COND=condition-name COMPACT. group-heading 
GRPSEP=—[-QINDENT 
NONE 
>—:EDATAGRP. >< 
-—— Syntax for Print Panels 
>>—: DATAGRP > 
E INDENT Lgonpscondit foncname= Lcompact— 
GRPSEP=——QINDENT 
NONE 
> : EDATAGRP. >< 
LU anopcneddings 


The data group (DATAGRP) tag is used to group 
data items and data selection fields in a data pres- 
entation area. This tag is allowed for display 
panels and print panels. One data group may be 
nested within another data group; up to four levels 
of data group nesting are allowed, including the 
outermost group. This tag is not valid if 
LAYOUT=HORIZ is specified for the data presenta- 
tion area (DATA) tag. 


The UIM does keep processing for data item 
groups. When data groups are nested within 
other data groups, keep processing is done for all 
the groups. If an outer group must be split, keep 
processing is attempted for groups nested within 
it. If the number of lines required for an entire 
group exceeds the number of lines remaining in 
the layout column, the entire group is forced to the 
next column. In the case of single-column layout, 
the entire group is forced to the next scrollable 
page. Any data group that becomes too large for 
one layout column begins at the top of one 
column and continues onto as many columns or 
pages as required for all items. 


Optional Attributes 


HELP=help-module-name 
Identifies online information explaining all 
items in the group. This attribute is allowed 
only for display panels. The help module 
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name may be a name imported from another 
panel group, but must follow the rules for 
names outlined earlier in this chapter. For 
more information on the rules for naming, see 
“Name Syntax” on page A-4. 


A single help module name must be associ- 
ated with every item in the area. If the HELP 
attribute is specified on the DATA tag, the 
help applies to all groups and items in the 
area, and the HELP attribute is not allowed on 
any data group (DATAGRP), data item 
(DATAI), data selection field (DATASLT), and 
data selection field choice (DATASLTC) tags 
in the area. 


If the HELP attribute is specified on the 
DATAGRP tag, the help applies to all items in 
the group, and the HELP attribute is not 
allowed on any DATAI, DATASLT, 
DATASLTC, or nested DATAGRP tags within 
the data group. 


If no HELP attribute is specified on the DATA 
tag or on any outer or nested DATAGRP tags, 
the HELP attribute is required on all DATAI and 
DATASLT tags within the group. 


NAME=data-group-name 
The name associated with the group. This 
name can be used with the Add Pop-Up 
Window (QUIADDPW) API to position a 


window near this data group. This attribute is 
allowed only for display panels. 


For more information on the rules for naming, 
see “Name Syntax” on page A-4. 


GRPSEP=INDENT | NONE | QINDENT 


Specifies what type of visual separation 
should be used to distinguish the items in the 
group. 


INDENT is used to indent the left-most 
column, prompt, or value for every data item, 
group heading of a nested data group, or data 
selection field within the group by two posi- 
tions. Only the left-most column is indented. 
The group heading is not indented. 


QINDENT is used to indent each data item or 
nested data group or data selection field, 
except the first one in the group. The first 
item or imbedded group within this data item 
group are not indented. All other items, fields, 
and imbedded groups are indented. Both the 
prompt column and the value column of a 
data item or data selection field are indented 
by two positions. The group heading of an 
nested data group and all items within it are 
indented by two positions. 


The determination of which data items, 
selection fields and groups are indented is 
made when the panel group is created and is 
unaffected by conditioning. This option pre- 
sents data items in the same format the 
control language (CL) prompter uses for quali- 
fied names. Because qualified name 
indenting of a value would be backward for a 
BIDI=RTL panel group, the value column is 
not indented when QINDENT is specified for a 
BIDI=RTL panel group. The prompt text of 
each item after the first one is still indented. 


NONE does not indent any data items, data 
selection fields, or nested data item groups in 


DATAGRP Tag 


the group. This option is not recommended 
when group heading text is specified. It can 
be used to group related data items, data item 
groups, and data selection fields together 
without a group heading. It does this by 
defining a compact group of items and nested 
groups in a non-compact area. 


COND=condition-name 
The group is displayed or printed only if the 
condition specified is true. All tags within the 
group appear only if this data group appears. 
The condition must be defined in the panel 
group prolog with the condition definition 
(COND) tag. 


COMPACT 
If COMPACT is specified, then no blank lines are 
left between individual items or nested data 
group headings. If this data group is nested 
inside another data group for which COMPACT is 
specified, COMPACT is implied for this data 
group whether it is specified or not. 


Optional Text 


group-heading 
The heading placed above the data items of 
the group. The text occupies only one line of 
the panel, but may span several columns. 
The text must appear on the same line or next 
line as the tag and can only contain the 
reverse text (RT) tag. 


If the text is omitted, no lines are allocated on 

the display for a group heading, but the items 

between the DATAGRP and EDATAGRP tags 
are processed as a group with respect to keep 
processing on the display and other UIM oper- 
ations. 


A colon is added to the end of the text if one 
is not already specified and if there is room for 
it. 
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DATAI Tag 


DATAI (Data Item) 


;—— Syntax for Display Panels 
>>—: DATAI—VAR=dialog-variable-name—USAGE=—— OUT > 
Linour LfELPhelpsmodale-nane=. 
=data-item-name 
NAME=d i Bical eee 
PMTLOC= ABOVE— CHCLOC=——ABOVE 
> | > 
| LEFT JUSTIFY=——LEFT ie No | 
ALIGN=—;—RIGHT: RIGHT Pe YES 
START START 
END END 
> [ > 
YES | | YES | | NO 
CSRLOC= No a DISPLAY= No a AUTOENTR=—LYES 
> > 
Lconp=condi A onenanes LprompT= ‘action-text = LpsPVALUE=dialog- var tub achat 
> >< 
Leggtasttenstent— 
;-—— Syntax for Print Panels 
>>—: DATAI—VAR=dialog-variable-name 2 | > 
USAGE=0UT q pee ORE 
PMTLOC=——ABOVE 
> > 
I ge | LEFT JUSTIFY=——LEFT 
CHCLOC=——ABOVE ALIGN=—;—-RIGHT RIGHT 
START START 
END END 
> >< 
LGoNbecond?tion-name— Ladpactvensbent= 


The data item (DATAI) tag defines an item placed 
in a data presentation area. This tag is allowed 
for display panels and print panels. 


The data item extender (DATAIX) tag can be used 
to specify additional dialog variables, which are 
displayed as part of the data item. The data 
selection choices (DATAC) tag can be used to 
specify possible choices text, which is displayed 
as part of the data item. The DATAIX and 
DATAC tag are considered part of the DATAI tag 
with respect to formatting, conditioning, scrolling, 
and help. 


Note that the prompt, field and extenders, and 
possible choices text must fit within the data area. 


A-42 Application Display Programming V4R1 


The UIM does not allow an individual data item to 
be split while scrolling. 


Required Attributes 


VARz=dialog-variable-name 
The name of the dialog variable constructing 
the data item. The current value of the dialog 
variable is displayed or printed. 


If the item appears in an area with LAYOUT=1 
specified on the data presentation area 
(DATA) tag, its value can exceed the width of 
the choice column. In this case, the value is 
presented as a single field that wraps onto as 
many display lines as necessary. If LAYOUT=2 
is specified on the DATA tag, the width of the 
value must fit between the starting position 


determined from the second data column 
(DATACOL) tag and the ending position for 
the layout column. 


For a data presentation area specified with 
LAYOUT=HORIZ, if there are already data items 
on the display line and if the length of the 
prompt plus the value does not fit on the 
current line and allow a five column separator 
between data items, the prompt and values 
are placed on the next display line. For hori- 
zontal layout, the prompt plus the value must 
fit on a single line of the panel. 


USAGE=OUT | INOUT 


Indicates the display use of the data item. 
This attribute is required for display panels 
and is optional for print panels. 


USAGE=OUT defines an output data item. OUT 
indicates that the variable displayed is for 
output only and cannot be changed by the 
user. 


USAGE=INOUT defines a data entry item. 
INOUT indicates that the variable is for data 
entry and can be changed by the user. 


Optional Attributes 
HELP=help-module-name 


Identifies online information which explains the 
data item. This attribute is allowed only for 
display panels. The name of the help module 
can be a name imported from another panel 
group, but must follow the rules for names 
outlined earlier in this chapter. For more infor- 
mation on the rules for names, see “Name 
Syntax” on page A-4. 


A single help module name must be associ- 
ated with every item in the area. If the HELP 
attribute is specified on the DATA tag, the 
help applies to all groups and items in the 
area, and the HELP attribute is not allowed on 
any data group (DATAGRP) and DATAI tags 
in the area. 


If the HELP attribute is specified on the 
DATAGRP tag, the help applies to all data 
items in the group and the HELP attribute is not 
allowed on DATAI tags within the group. 


If no HELP attribute is specified on the DATA 
tag or on DATAGRP tags containing a data 
item, the HELP attribute is required on the 
DATAI tag. 


DATAI Tag 


To provide the user with easy access to the 

online information for a LAYOUT=HORIZ data 

area, use the HELP attribute on the DATA tag 
instead of the HELP attribute on the individual 
DATAI tags in the horizontal area. 


The HELP attribute applies to all DATAIX tags 
associated with this data item. 


NAME-=data-item-name 


The name associated with the item. This 
name can be used with the Add Pop-Up 
Window (QUIADDPW) API to position a 
window near this data item. This attribute is 
allowed only for display panels. 


For more information on the rules for naming, 
see “Name Syntax” on page A-4. 


PMTLOC=BEFORE | ABOVE 


Governs the placement of the variable value 
in relationship to the prompt text for the data 
item. 


BEFORE indicates that the prompt text is 
placed before (to the left of) the variable 
value. The variable value begins on the line 
the prompt text ended on. 


ABOVE indicates that the prompt text is 
placed above the data item variable. The var- 
iable is indented two spaces from the begin- 
ning of the prompt text. ABOVE is not 
allowed when LAYOUT=HORIZ is specified on 
the DATA tag. 


If the prompt text is placed above the data 
item variable as a result of ABOVE, the ALIGN 
attribute on this tag is not used for formatting. 


All data item extenders placed on a new line 
as a result of NEWLINE=CALC or NEWLINE=YES 
on the DATAIX tag begin in the same column 
as the data item variable. 


CHCLOC=AFTER | ABOVE 


Governs the placement of the data choices 
text in relationship to the variable value for the 
data item. 


AFTER indicates that the data choices text is 
placed after the variable value. This is either 
on the same line or on the line below the end 
of the variable value. 


ABOVE indicates that the data choices text is 
placed above the data item variable. ABOVE 
is allowed only if PMTLOC=ABOVE is specified. 
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DATAI Tag 


This attribute is not allowed when 
LAYOUT=HORIZ is specified on the DATA tag. 


This attribute governs placement of data 
choices text only for DATAC tags immediately 
following the DATAI tag. DATAC tags fol- 
lowing a DATAIX tag are not affected by this 
attribute. 


ALIGN=LEFT | RIGHT | START | END 


Governs how the display value of the variable 
is positioned within the choice column defined 
by the second DATACOL tag. 


ALIGN=LEFT positions the leftmost character 
of the display value with the left edge of the 
choice column. 


ALIGN=RIGHT positions the rightmost char- 
acter of the display value with the right edge 
of the choice column. ALIGN=RIGHT is not 
allowed when LAYOUT=HORIZ is specified on 
the DATA tag. If the width of the display 
value, set by the WIDTH attribute on the class 
definition (CLASS) tag, exceeds the width of 
the choice column, ALIGN=RIGHT will work the 
same way as ALIGN=LEFT. 


START is a synonym for LEFT, and END is a 
synonym for RIGHT. 


JUSTIFY=LEFT | RIGHT | START | END 


Governs how the dialog variable is edited into 
the display value. The default for this attribute 
is the same value as was specified on the 
ALIGN attribute for this tag. 


For JUSTIFY=LEFT, the dialog variable is left- 
justified into the display value and leading 
blanks are preserved. 


For JUSTIFY=RIGHT, the dialog variable is 
right-justified into the display value and trailing 
blanks are stripped. 


START is a synonym for LEFT, and END is a 
synonym for RIGHT. 


REQUIRED=NO | YES 


Indicates whether or not the item is required. 
This attribute is allowed only for display 
panels. NO indicates that the item is not 
required. 


YES indicates that the item is required on the 
display and that the field is highlighted accord- 
ingly. YES is only valid if USAGE=INOUT is 
specified on this tag for the data item. 
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When REQUIRED=YES is coded, no explicit 
checks are made for user entry. However, 
REQUIRED=YES causes the UIM to do input 
editing and validity check processing, even if 
the user does not enter anything into the field. 
This allows you to use the validity checking 
(CHECK) tag to ensure that the user enters 
data into a required field. 


CSRLOC=YES | NO 


Indicates whether or not the cursor is allowed 
on the input field when the UIM does default 
cursor positioning. This attribute is allowed 
only for display panels. 


YES does not guarantee that the cursor is 
placed on the input field; it only indicates to 
the UIM that the cursor may be placed on the 
input field when the UIM does default cursor 
positioning. 


NO indicates that the cursor should not be 
placed on the field. CSRLOC=NO is intended 
for input fields such as the position-to field 
found in a data area above a list area. The 
cursor should not be placed on a position-to 
field when the panel is first displayed or after 
a position-to operation completes. When 
CSRLOC=NO is coded, it is still possible for the 
UIM to place the cursor on the field when 
default cursor positioning is performed. This 
may occur in the following situations: 


¢ All input fields on the current page of the 
panel are marked with CRSLOC=NO. 


e The input field is marked in error. 


e The cursor positioning under an applica- 
tion program's control specifies that the 
cursor should be placed on the field. 


The CSRLOC attribute applies to all DATAIX 
tags associated with this data item. 


DISPLAY=YES | NO 


Indicates whether or not the contents of the 
field are visible when the panel is displayed. 
This attribute is allowed only for display 
panels. 


YES indicates that the field is visible. 


NO indicates that the field is not visible. 
DISPLAY=NO is intended for input fields, such 
as a password field, which should not be 
visible. 


AUTOENTRENO | YES 


Indicates whether or not the field is an auto- 
matic enter input field. This attribute is 
allowed only for display panels. An automatic 
enter input field returns from the device to the 
host when the user enters a character, 
including a blank, into the last position of the 
field. This has the same effect as the user 
pressing the Enter key. 


NO indicates that the field is not an automatic 
enter field. 


YES indicates that the field is an automatic 
enter field. If YES is specified, USAGE=INOUT 
must also be specified on this tag. 


Although the UIM does not restrict its usage, 
AUTOENTR=YES is intended for input fields that 


DATAI Tag 


attribute used to define the function key. This 
updating is independent of the display value 
variable processing. 


The dialog variable specified must be defined 
on the CLASS tag as a CHAR or IGC variable 
whose length is the same as the width of the 
dialog variable specified on the VAR attribute of 
this tag. No translation list processing or 
value checking is performed for the value 
before it is placed in this variable. Character 
set and code page conversion are performed 
for this variable if the class of the variable 
named on the VAR attribute of this tag speci- 
fies that character set and code page conver- 
sion should be performed. 


Optional Text 


are one character wide. 
data-item-text 


COND=condition-name The text describing the data item. The text 


The item is in effect on a display only if the 
condition specified is true. All associated 
DATAC and DATAIX tags are displayed only if 
this data item appears on the display. The 
condition must be defined in the panel group 
with the condition definition (COND) tag. 


PROMPT=' action-text' 


The action occurring when F4=List is 
requested through the PROMPT dialog 
command. This attribute is allowed only for 
display panels. The PROMPT attribute is only 
allowed when USAGE=INOUT is specified for 
this data item. The valid forms of action-text 
are: 


¢ ‘CALL program-reference' 
For a description of the interface between 
the UIM and the exit program for the 
cursor-sensitive prompt, see the System 
API Reference. 


e 'RETURN positive-integer' 


For a description of these actions, see 
Appendix B, “UIM Dialog Commands” on 
page B-1. 


DSPVALUE=dialog-variable-name 


The dialog variable containing the current data 
entered in this data item. This attribute is 
allowed only for display panels and when the 
PROMPT attribute is coded on this tag. This 
variable is updated regardless of whether or 
not VARUPD processing is performed. The vari- 
able pool is updated based on the VARUPD 


may appear on more than one line and can 
only contain the reverse text (RT) tag. 


If the item appears in a data item group, it is 
indented as specified by the GRPSEP attribute 
on the DATAGRP tag. If the text is too long 
to fit in the prompt column, it is formatted onto 
additional lines as necessary to fit within the 
item column and is indented two spaces. 


If no text is specified, the data value appears 
without a prompt. Prompt text should be 
specified for all DATAI tags, except for the fol- 
lowing special cases: 


e When the data item is described com- 
pletely by the instruction or group heading 
text appearing above the item. 


e When the data item contains a value that 
is a logical continuation of the value for a 
data item appearing immediately before it 
in the panel. Conditioning may be used to 
present only as many lines on the panel 
as there are values available. 


The set of DATAI tags presenting this type 
of information should always be specified 
in a data group to ensure that the UIM 
keeps related values together on the 
display, and to present appropriate infor- 
mation in extended help for the panel. 
Prompt text should be specified for the 
first data item in the group, or heading text 
should be specified on the DATAGRP tag 
to describe the entire group. Help should 
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be specified for the group or for the entire 
area. 


When data groups are not used, the UIM 
may present items in different layout 


A-46 Application Display Programming V4R1 


columns or even on different scrollable 
pages. If the same help module is speci- 
fied for multiple data items, extended help 
for the panel repeats the online informa- 
tion for each item on the panel. 


DATAIX Tag 


DATAIX (Data Item Extender) 


;—— Syntax for Display Panels 


>>— : DATAIX—VAR=dialog-variable-name—USAGE= Eel Zi > 
INOUT | CALC 
NEWLINE= ae 
YES 
> > 
L SE el LEFT | 
ITEMSEP=——i tem-separator-value ALIGN=——RIGHT 
END: 


START 
END: 


a | | | fe) 
JUSTIFY=——LEFT NO YES 
fee REQUIRED= [ves pIspLay-—L-no 


Lprompr= ‘action-text = LpspVALUE=dialog- bdntabiesnanes | 


NO 
AUTOENTR=—L-YES 


> >< 
;-—— Syntax for Print Panels 
>>—: DATAIX—VAR=dialog-variable-name i 7 > 
USAGE=0UT I CALC 
NEWLINE=——NO 
YES 
> > 
i alee || LEFT | 
ITEMSEP=——i tem-separator-value ALIGN=——RIGHT 
START 
END: 
> >< 


START 
END: 


LjustIFY=—-—LEFT , 
Ener 


The data item extender (DATAIX) tag provides an 
additional dialog variable to be associated with a 
data item (DATAI) tag. This tag is allowed for 
display panels and print panels. 


The DATAIX tags must appear after the corre- 
sponding DATAI tag. More than one DATAIX tag 
may be specified after the DATAI tag to provide 
several dialog variables. If no DATAIX tags are 
entered, only one dialog variable, specified on the 
DATAI tag, appears for the data item. 


The DATAIX and data choices (DATAC) tags can 
be specified in any order. The order in which they 


are specified determines where they appear in 
relationship to the dialog variable of the DATAI 
tag. 


Required Attributes 


VARz=dialog-variable-name 
The name of the additional dialog variable dis- 
played with the previous DATAI tag. The 
current value of the dialog variable is dis- 
played or printed. 


For a LAYOUT=1 data presentation area, the 
display value can exceed the width of the 
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panel. In this case, the value is presented as 
a single field that wraps onto as many lines as 
necessary. For a LAYOUT=2 data presentation 
area, the display value must fit on one line. 


For a LAYOUT=HORIZ data presentation area, 
the data item prompt, value, and all DATAIX 
values must all fit on a single line of the panel. 
If there are already data items on one line of 
the panel and if the prompt text and dialog 
variable for the DATAI tag plus the value of 
this dialog variable do not fit on the current 
line and still allow a five-column separator 
between data items, the entire data item, 
including this item extender, are placed on the 
next line of the panel. 


USAGE=OUT | INOUT 


The display use of the data item. This attri- 
bute is required for display panels but is 
optional for print panels. 


USAGE=OUT defines an output data item. OUT 
indicates that the variable displayed is for 
output only and cannot be changed by the 
user. 


USAGE=INOUT defines a data entry item. 
INOUT indicates that the variable is for data 
entry and can be changed by the user. 


Optional Attributes 
NEWLINE=CALC | NO | YES 


Governs the placement of the variable for the 
data item extender in relationship to the vari- 
able value for the data item, possible choices 
text, and previously-defined data item 
extenders. 


NEWLINE=CALC indicates that the UIM deter- 
mines the placement of the variable. The var- 
iable is placed on the same line as the 
previous dialog variable if all of the following 
conditions are true: 


e The variable fits within the value column, 
defined by the second data column 
(DATACOL) tag of the current line. 


e The DATAIX tag is not immediately fol- 
lowed by a DATAC tag. 


e The current line is not wrapped from the 
previous line 


If any of the above conditions are not true, the 
data item extender is placed on the next 
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display or print line. It is positioned according 
to the ALIGN attribute of this tag. 


When NEWLINE=CALC is specified in a data 
presentation area with LAYOUT=HORIZ speci- 
fied, the value is placed on the same line as 
the previous value. 


NEWLINE=NO indicates that the value should 
be placed on the same line and to the right of 
the previous value. The previous value is the 
dialog variable for either the DATAI tag or a 
previous DATAIX tag. If the DATAIX tag 
appears immediately after a DATAC tag, 
NEWLINE=NO is not allowed. 


NEWLINE=YES indicates that the value should 
be placed on the next display or print line. 
NEWLINE=YES is not allowed for data presenta- 
tion areas with LAYOUT=HORIZ specified. 


ITEMSEP=2 | item-separator-value 


Indicates how many spaces separate the 
dialog variable of this data item extender and 
the previous dialog variable. 


For data presentation areas with LAYOUT=1 or 
LAYOUT=2, the maximum value for this attribute 
is the width of the choice column, as defined 
by the second DATACOL tag. For data pres- 
entation areas with LAYOUT=HORIZ specified, 
the maximum value for this attribute is 5. The 
default value is 2, and the minimum value is 
1. 


The ITEMSEP attribute is not allowed when 
NEWLINE=YES is specified on this tag, and has 
no effect when NEWLINE=CALC is specified 
and the extender variable is placed on a new 
line. 


ALIGN=LEFT | RIGHT | START | END 


Governs how the display value is positioned 
within the choice column defined by the 
second DATACOL tag. 


If the dialog variable is preceded by the dialog 
variable for the DATAI tag or by a previous 
DATAIX tag, the ALIGN attribute has no effect 
on the position of the display value within the 
choice column. 


If the dialog variable is the first variable on the 
display or print line, the ALIGN attribute formats 
text as follows: 


e ALIGN=LEFT positions the leftmost char- 
acter of the display value with the left 
edge of the choice column. 


¢ ALIGN=RIGHT positions the rightmost 
character of the display value with the 
right edge of the choice column. If the 
width of the display value exceeds the 
width of the choice column, ALIGN=RIGHT 
works the same as ALIGN=LEFT. 


ALIGN=RIGHT is not allowed for data presen- 
tation areas with LAYOUT=HORIZ specified. 


START is a synonym for LEFT and END is a 
synonym for RIGHT. 


JUSTIFY=LEFT | RIGHT | START | END 


Governs how the dialog variable is edited into 
the display value. The default for this attribute 
is the same value as was specified or 
defaulted to on the ALIGN attribute of this tag. 


For JUSTIFY=LEFT, the dialog variable is left- 
justified into the display value. Leading blanks 
are preserved. 


For JUSTIFY=RIGHT, the dialog variable is 
right-justified into the display value and trailing 
blanks are stripped. 


START is a synonym for LEFT and END is a 
synonym for RIGHT. 


The JUSTIFY attribute is ignored for variables 
defined as UCS-2. 


REQUIRED=NO | YES 


NO indicates that the item is not required. 
This attribute is allowed only for display 
panels. 


YES indicates that the item is required on the 
display and that the field is highlighted accord- 
ingly. YES is only valid if USAGE=INOUT is 
specified for the data item extender. 


When REQUIRED=YES is coded, no explicit 
checks are made for user entry. 
REQUIRED=YES causes the UIM to perform 
input editing and validity check processing, 
even if the user does not enter anything into 
the field. This allows you to use the validity 
checking (CHECK) tag to ensure that the user 
enters data into a required field. 


DISPLAY=YES | NO 


Indicates whether or not the field is visible 
when the panel is displayed. This attribute is 
allowed only for display panels. YES indi- 
cates that the field is visible. 


NO indicates that the field is not visible. 
DISPLAY=NO is intended for input fields such 


DATAIX Tag 


as a password field, which should not be 
visible. 


PROMPT=' action-text' 


The action occurring when F4=List is 
requested through the PROMPT dialog 
command. This attribute is allowed only for 
display panels, and when USAGE=INOUT is 
specified on this tag for this data item 
extender. The valid forms of action text are: 


¢ ‘CALL program-reference' 
For a description of the interface between 
the UIM and the exit program for the 
cursor-sensitive prompt, see the System 
API Reference. 


e ‘RETURN positive-integer' 


For a description of these actions, see 
Appendix B, “UIM Dialog Commands” on 
page B-1. 


DSPVALUE=dialog-variable-name 


The dialog variable containing the current data 
entered into this data item extender. This 

attribute is allowed only for display panels and 
when the PROMPT attribute is coded on this tag. 


This variable is updated regardless of whether 
or not VARUPD processing is performed. The 
variable pool is updated based on the VARUPD 
attribute used to define the function key. This 
updating is independent of the display value 
variable processing. 


The dialog variable specified must be defined 
on the class definition (CLASS) tag as a 
CHAR or IGC variable whose length is the 
same as the width of the dialog variable speci- 
fied on the VAR attribute of this tag. 


No translation list processing or value 
checking is performed for the value before it is 
placed in this variable. Character set and 
code page conversion are performed for this 
variable if the class of the variable named on 
the VAR attribute of this tag specifies that char- 
acter set and code page conversion should be 
performed. 


AUTOENTRENO | YES 


Indicates whether or not the field is an auto- 
matic enter input field. This attribute is 
allowed only for display panels. An automatic 
enter input field returns from the device to the 
host when the user enters a character, 
including a blank, into the last position of the 
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field. This has the same effect as the user 
pressing the Enter key. 


NO indicates that the field is not an automatic 
enter field. This is the default value. 
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YES indicates that the field is an automatic 
enter field. If YES is specified, USAGE=INOUT 
must also be specified on this tag. Although 
the UIM does not restrict its usage, 
AUTOENTR=YES is intended for input fields that 
are one character wide. 


DATASLT tag 


DATASLT (Data Selection Field) 


p>>—: DATASLT—TYPE= SINGLE 
MULTI 


| VaRedielagevantabtesnone| 


> 


> 


> 
[ietpshelpemodulecname LyaMe=select donapreleenane™ LpwtLoc-—-gerore—— 


ABOVE 


> 


Lcetertion-pielasprompt-text 


L REQUIRED= a | LAUTOENTER= feo | Conb=eond:Lenenane= 
YES YES 


:EDATASLT. 


>< 


The data selection field (DATASLT) tag defines a 
selection field in the data presentation area. This 
tag is allowed only for display panels. 


The DATASLT may be a single- or multiple-choice 
selection field. The selection field is fixed in 
content and number of choices. A data selection 
field can only be specified when LAYOUT=1 or 2 on 
the data presentation area (DATA) tag. 


The data selection field choice (DATASLTC) tag 
specifies the choices for the selection field. The 
DATASLTC tag is part of the DATASLT tag with 
respect to formatting, conditioning, scrolling, and 
help. 


The prompt, field, and choices must fit within the 
data area. The UIM does not allow a selection 
field to be split while scrolling. 


Other tags can be nested within the DATASLT 
tag. These tags are listed in the following table. 
The table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-6. Tag Allowed Between the DATASLT and 
EDATASLT Tags 


Tag Name Order Use Page 
DATASLTC 1 D A-55 
(Data selection 

field choice) 


Required Attributes 


TYPE=SINGLE | MULTI 
Specifies whether or not the selection field is 
a selection field for single or multiple choices. 


SINGLE indicates that the selection field is for 
a single choice. 


MULTI indicates that the selection field is for 
multiple choices. 


Optional Attributes 


VARz=dialog-variable-name 
The name of the dialog variable used to con- 
struct the single-choice selection field. This 
attribute is required for TYPE=SINGLE. The 
variable is presented on the display if 
TYPE=SINGLE, and must be declared with a 
BASETYPE of BIN(31) on the class definition 
(CLASS) tag. This variable contains the 
option number of the choice selected by the 
user. If no choices are selected, the variable 
returns a zero. The current value of the 
dialog variable is presented on the display. 


If TYPE=MULTI is specified on this tag, this 
attribute is not allowed. 


HELP=help-module-name 
Identifies online information explaining the 
purpose of the data selection field. The name 
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of the help module may be a name imported 
from another panel group, but the name must 
follow the rules for names outlined earlier in 
this chapter. For more information on the 
rules for names, see “Name Syntax” on 

page A-4. 


A single help module name must be associ- 
ated with every item in the area. If the HELP 
attribute is specified on the DATA tag, the 
help applies to all groups and items in the 
area, and the HELP attribute is not allowed on 
any data group (DATAGRP) and DATASLT 
tags in the area. 


If the HELP attribute is specified on the 
DATAGRP tag, the help applies to all data 
selection fields in the group, and the HELP 
attribute is not allowed on DATASLT tags 
within the group. 


If no HELP attribute is specified on the DATA 
tag nor on DATAGRP tags containing a data 
selection field, the HELP attribute is required on 
the DATASLT tag. 


NAME=selection-field-name 


The name associated with the selection field. 
This name can be used later with the Add 
Pop-Up Window (QUIADDPW) API to position 
a window associated with this selection field. 
For more information on the rules for naming, 
see “Name Syntax” on page A-4. 


PMTLOC=BEFORE | ABOVE 


Governs the placement of the prompt text in 
relationship to the input field associated with 
the selection field. 


BEFORE indicates that the prompt text is 
placed before (to the left of) the variable value 
of the data field. The variable value begins on 
the same line on which the prompt text ended. 
BEFORE is the default. 


ABOVE indicates that the prompt text is 
placed above the data item variable. The var- 
iable is indented two spaces from the begin- 
ning of the prompt text. 


REQUIRED=NO | YES 


This attribute is allowed only for 
TYPE=SINGLE. NO indicates that the field is 
not required. NO is the default value. 


YES indicates that the field is required on the 
display, and the field is highlighted accord- 
ingly. When REQUIRED=YES is coded, no 
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explicit checks are made for user entry. 
However, YES causes the UIM to perform 
input editing and validity check processing 
even if the user does not enter anything into 
the field. This allows you to use the validity 
checking (CHECK) tag to ensure that the user 
enters data into a required field. 
REQUIRED=YES cannot be specified when 
TYPE=MULTI is specified on this tag. 


AUTOENTRENO | YES 


Indicates whether or not the field is an auto- 
matic enter input field. An automatic enter 
input field returns the screen from the device 
to the host when the user enters a character, 
including a blank, into the last position of the 
field. This has the same effect as the user 
pressing the Enter key. 


NO indicates that the field is not an automatic 
enter field. This is the default value. 


YES indicates that the field is an automatic 
enter field. Although the UIM does not restrict 
its usage, AUTOENTR=YES is intended to be 
used only on input fields that are one char- 
acter wide. YES is not allowed when 
TYPE=MULTI is specified on this tag. 


COND=condition-name 


The selection field is displayed only if the con- 
dition specified is true. Associated 
DATASLTC tags are displayed only if this 
selection field appears on the display. The 
condition must be defined in the panel group 
with the condition definition (COND) tag. 


Optional Text 


selection-field-prompt-text 


The text which describes the selection field. 
The text may appear on more than one line 
and can contain only the reverse text (RT) 
tag. The length of the text is 255 bytes or 
less. 


If the selection field appears in a data item 
group, it is indented as specified by the 
GRPSEP attribute on the DATAGRP tag. If the 
text is too long to fit in the prompt column, it is 
formatted on the following lines as necessary 
to fit within the column and indented two 
spaces from the beginning of the first line. 


If no text is specified, the selection field 
appears without a prompt. Prompt text should 
be specified for all DATASLT tags, except for 


when the selection field is described com- 
pletely by the instruction or group heading text 
appearing above the item. 


Example 1: Data Entry Panel 


The example shows a sample data entry panel. 
The panel has 2 selection fields with the defaults 
supplied by the calling program by previously 
setting the dialog variables for the function. 


UIM Source 


:class name=select 
basetype='bin 31'. 

:var name=prtstyle 
class=select. 

:var name=duplex 
class=select. 


:panel name=entryl 
help=hentryl 
topsep=space 


.Sample Entry Panel 
:data depth='*' 
bodysep=both. 
:topinst.Type choices, press Enter. 
:datacol width=30. 
:datacol width='*'. 
:dataslt help=hstyle 
var=prtstyle 
type=single 
.Type style for printing 
:datasltc help=hstylep 
option=1 
.Prestige elite (12 pitch) 
:datasltc help=hstylec 
option=2 
.Courier (10 pitch) 
:datasltc help=hstylees 
option=3 


DATASLT tag 


.Essay standard (proportional) 
:datasltc help=hstyleeb 

option=4 

.Essay bold (proportional) 
:edataslt. 
:dataslt type=single 

help=hdup1x 

var=duplex 

.Duplex 
:datasltc help=hdupIxy 

option=1 

.Print both sides of paper 
:datasltc help=hdup1Ixn 

option=2 

-Print one side only 
:edataslt. 
:edata. 
:epanel. 
:invellip. 


Results 


Sample Entry Panel 
Type choices, press Enter. 


. Prestige elite 

. Courier (10 pitch) 

. Essay standard (proportional) 
. Essay bold (proportional) 


Type style for printing... 1 


. Print both sides of paper 
. Print one side only 


DUPLEX +c: 35 yeaa gE ee es 1 


In this example, the PRTSTYLE and DUPLEX 
dialog variables must be BIN 31, and the option 
value selected is returned to the calling program in 
these variables. 


Example 2: Multiple-Selection 
Field 


This example shows a multiple-selection field. 
The user selects the values by typing a slash (/) 
or the country-designated character into the entry 
field preceding the desired options. More than 
one heading option may be selected. 
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UIM Source 


:class name=sfield 
basetype='char 1'. 

:var name=hdoptsb 
class=sfield. 

:var name=hdoptsu 
class=sfield. 

svar name=hdoptsuc 
class=sfield. 

:var name=hdoptssn 
class=sfield. 

:var name=hdoptstm 
class=sfield. 

:var name=hdoptsdt 
class=sfield. 

:panel name=xxx 
keyl=x1.Heading Options 

:data depth='*' 
bodysep=both. 

:topinst.Select one or more 

choices, press Enter. 

:datacol width=30. 

:datacol width='*'. 

:datas|lt type=multi 
help=haward.Heading options 

:datasltc var=hdoptsb 
help=hbold.Bold 

:datasltc var=hdoptsu 
help=hund1 .Underline 

:datasltc var=hdoptsuc 
hel p=hupperc. Uppercase 

:datasltc var=hdoptssn 
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help=hsecn.Section numbers 

:datasltc var=heoptstm 
help=htime.Time 

:datasltc var=hdoptsdt 
help=hdate.Date 

:edataslt. 

:edata. 


Results 


Heading Options 
System: = XXXXXXXX 
Select one or more choices, press Enter. 


Heading options ....... _ Bold 
_ Underline 
_ Uppercase 
_ Section numbers 
_ Time 
_ Date 


If the user chooses Underline, Section numbers, 
and Date in this example, the value in the dialog 
variables are: 


¢ hdoptsb=0 
¢ hdoptsu=1 
¢ hdoptsuc=0 
¢ hdoptssn=1 
¢ hdoptstm=0 
¢ hdoptsdt=1 


DATASLTC tag 


DATASLTC (Data Selection Field Choice) 


p>—: DATASLTC 
L cHorce=dialog-variable-name—| Loption=opt ‘onchumber! 


> 

LyaRcaialogsvarianionane™| LaECRshetpemodatename=| Lconp=condition-name— 
> 

Lavaticednditionsnene L_aVLMSGID=message-identifier— 
> 


The data selection field choice (DATASLTC) tag 
defines a possible choice for a single- or multiple- 
choice selection field. This tag is allowed only for 
display panels. It is not valid if LAYOUT=HORIZ is 
specified on the data presentation area (DATA) 
tag for the area. 


The DATASLTC tags must appear after the corre- 
sponding data selection field (DATASLT) tag and 
at least one DATASLTC tag must be specified 


between the DATASLT and the EDATASLTC tags. 


The DATASLTC tag defines the choices for the 
selection field. 


Optional Attributes 


CHOICE=dialog-variable-name 
The name of a dialog variable containing the 
possible choices text to be displayed. The 
dialog variable must be defined so that the 
text fits on a single line. 


Dialog variables must be defined with a 
BASETYPE of CHAR, IGC, or BIN on the class 
definition (CLASS) tag. 


The error state of the dialog variable is not 
used for determining the highlighting of the 
text. 


If the CHOICE attribute is specified, the text-for- 
choices cannot be specified. 


Special formatting for IGC. (The abbrevi- 
ation IGC is used in commands and keywords 
to represent double-byte character set func- 
tions.) When a dialog variable with a 
BASETYPE of IGC is specified on the CLASS 
tag, the UIM does special formatting. If the 
variable value begins with a shift-out character 
(X'OE'), the UIM shifts the value one char- 


LavimsGr= 'qualified-message-file-name = 


>< 


Eepexdaporscnotees”. 


acter to the left to preserve vertical alignment 
with data choices on other lines. 


OPTION=option-number 
The number assigned to this option. Option 
numbers are integers in the range of 1 to 99. 
This attribute is required if specified within a 
DATASLT tag that has TYPE=SINGLE speci- 
fied, but cannot be used if TYPE=MULTI is 
specified. 


Selection field choices are displayed in the 
order defined in the selection field. If the 
numbering of two choices is not consecutive, 
a blank line is automatically placed between 
the two choices. If two choices have the 
same option number and both are 
conditioned-on at the same time, the choice 
defined first is displayed. 


VAR=dialog-variable-name 
The name of the dialog variable used to indi- 
cate whether or not the selection field choice 
is selected. This attribute is required for 
TYPE=MULTI. The variable must be declared 
with a BASETYPE of CHAR 1 on the CLASS 
tag. 


If the choice is not selected, the value of the 
dialog variable is '0'. If the choice is selected, 
a value of '1' is returned in the dialog variable. 
If the current value of the variable is '1' when 
the screen is displayed, a slash (/) is dis- 
played on the screen. The user may enter 
either a slash or the country-designated char- 
acter and a '1' is returned to the user. Which- 
ever character is used for selection by the 
user is shown when the panel is redisplayed. 
If the current value of the dialog variable is 
something other than '1' when the panel is 
displayed, the variable is presented as unse- 
lected. 
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The VAR attribute is required if TYPE=MULTI on 
the DATASLT tag. If TYPE=SINGLE is speci- 
fied, the VAR attribute is not allowed. 


HELP=help-module-name 


Identifies online information explaining the 
purpose of the selection field choice. The 
name of the help module may be a name 
imported from another panel group, but must 
follow the rules for names outlined earlier in 
this chapter. For more information on the 
rules for names, see “Name Syntax” on 
page A-4. 


This attribute is allowed only when the HELP 
attribute is specified on the DATASLT tag that 
contains this DATASLTC tag. 


If the HELP attribute is specified on a 
DATASLTC tag within a selection field, all 
DATASLTC tags within that selection field 
must have the HELP attribute specified. 


For multiple-choice selection fields with 
SELECT=MULTI specified on the DATASLT tag, 
the online information identified by this attri- 
bute is included as part of the contextual help 
displayed when the cursor is positioned any- 
where within the selection field. 


For single-choice selection fields with 
SELECT=SINGLE specified on the DATASLT 
tag, the online information identified by this 
attribute is displayed when help is requested 
while the cursor is positioned on the choice 
text for this tag. This online information is 
also included as part of the contextual help 
displayed when the cursor is positioned within 
the selection field but not on the text for one 
of the choices within the field. This includes 
when the cursor is positioned on the prompt 
text for the selection field or in the entry field 
for the selection field. If the cursor is in the 
entry field and a valid choice is entered, when 
help is requested, the help for that choice is 
displayed. 


COND=condition-name 


The selection field choice is in effect on the 
panel only if the condition specified is true. 
The condition must be defined in the panel 
group prolog with the condition definition 
(COND) tag. When the choice is 
conditioned-off, the selection field choice does 
not appear in the selection field and the help 
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for the choice is not included in requests to 
display help. 


AVAIL=condition-name 


The name of a condition indicating whether or 
not the selection field choice is available. The 
condition must be defined in the panel group 
prolog with the COND tag. 


When the condition is true, the selection field 
choice is available. When the condition is 
false, the selection field choice is not avail- 
able. Any condition specified on the COND 
attribute on this tag takes precedence over 
this attribute. 


Unavailable choices are displayed with a color 
change and an asterisk (*) overlaying the first 
part of the choice option number. 


The AVAIL attribute cannot be specified if the 
selection field is specified as TYPE=MULTI on 
the DATASLT tag. 


AVLMSGID=message-identifier 


The message identifier of the message dis- 
played when the selection field choice is 
selected when it is not available as specified 
by the AVAIL attribute on this tag. This attri- 
bute is allowed only when the AVAIL attribute 
is specified. 


If this attribute is not specified, the UIM dis- 
plays a default message stating that the 
choice is not currently available. 


AVLMSGF=' qualified-message-file-name' 


The message file name containing the 
message identifier. This attribute is allowed 
when the AVLMSGID attribute on this tag is 
specified. If the DFTMSGF attribute is not speci- 
fied on the panel group (PNLGRP) tag and 
the AVLMSGID attribute on this tag is specified, 
this attribute must be specified. 


Optional Text 


text-for-choices 


This text is an implied paragraph. When the 
display is formatted, any text that does not fit 
onto one line is formatted on the following 
lines and indented two columns. The text can 
be a maximum of 255 characters and can only 
contain the reverse text (RT) tag. Text-for- 
choices is required unless the CHOICE attribute 
is specified on this tag. 


DL, DT, DD, DTHD, DDHD Tags 


DL (Definition List) 


>> 


Lcom pact— 


» 4-01 .de fini tion-term—<0b. definition | 


Ls DTHD defini Fonsrenn bende = DDHD .defini Poncheader| 


> 


: EDL. >< 


The definition list (DL) is a list of words or phrases 
and their corresponding definitions, descriptions, 
or explanations. This tag requires a matching end 
tag. A definition list is only allowed in information 
areas and help areas. 


The terms being defined and their definitions are 
identified by the definition term (DT) tag and the 
definition description (DD) tag. A heading for the 
column of terms and the column of definitions can 
be identified by the definition term heading 
(DTHD) tag and the definition description heading 
(DDHD) tags, respectively. 


Definition lists can occur anywhere in text; they 
can be nested within other lists or definition lists, 
and other lists can be nested within definition lists. 


Two DT or DD tags cannot be used consecutively. 


Other tags can be nested within the DL tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-7. Tags Allowed Between the DL and EDL 
Tags 


Tag Name Order Use Page 
FIG 1 B A-59 
(Figure) 


Table A-7. Tags Allowed Between the DL and EDL 
Tags 


Tag Name Order Use Page 
LINES 1 B A-77 
(Unformatted 

lines) 

XMP 1 B A-171 
(Example) 

NT 1 B A-117 
(Note) 

P 1 B A-121 
(Paragraph) 

PC 1 B A-131 
(Paragraph con- 

tinuation) 

LP 1 B A-107 
(List part) 

OL 1 B A-118 
(Ordered list) 

SL 1 B A-152 
(Simple list) 

UL 1 B A-164 
(Unordered list) 

PARML 1 B A-129 
(Parameter list) 

DL 1 B A-57 


(Definition list) 


Optional Attribute 


COMPACT 
Formats the list without the blank line between 
the items. 


Required Tags 


DT.definition-term 
The text for the definition term. The term 
formats the way it is entered, in highlight 
phrase 2 (HP2). 
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DL, DT, DD, DTHD, DDHD Tags 


The term is assumed to be 10 single-byte 
character set (SBCS) characters or 4 double- 
byte character set (DBCS) characters, and 
starts at position 2 relative to the left margin. 

If the term is longer than the assumed number 
of characters, it is extended into the 
description line. 


DD.definition 
The text for the definition. The description of 
the term is an implied paragraph and can 
contain text items. Additional paragraphs can 
be inserted following the description para- 
graph, using the paragraph (P) tag. 


The description starts at position 14 relative to 
the left margin, unless the term extends into 
the description area. 


Optional Tags 


DDHD.definition-header 
The text for the definition header. The header 
formats the way it is entered, in highlight 
phrase 2 (HP2). 


DTHD. definition-term-header 
The text for the definition term header. The 
header formats the way it is entered, in high- 
light phrase 2 (HP2). 


Example 1: Definition List 


This example illustrates how a definition list with 
headings will format. 


UIM Source 


:DL. 

:DTHD.Term 
:DDHD.Description 
:DT.DL 

:DD.This is a sample 
definition list term 
and description. 
:DT.EDL 

:DD.Here is another. 
:EDL. 
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Results 
Term Description 
DL This is a sample definition list 


term and description. 


EDL Here is another. 


Example 2: Compact Definition 
List 


This is a definition list using the COMPACT attribute. 


UIM Source 


:DL compact. 

:DT.COMPACT 

:DD.This causes the list 
to be compacted, so the 
blank lines are removed. 
:DT.ANOTHER 

:DD.Here is another. 
:EDL. 


Results 


COMPACT This causes the list to be 
compacted, so the blank lines are 
removed. 

ANOTHER Here is another. 

Care should be taken when using unformatted 

lines (LINES), figure (FIG), and example (XMP) 

tags within a definition list, because text that does 
not fit on one line wraps to column one of the next 
line. Lines and figures start at the current left 
margin and examples are indented four spaces 
from the current left margin. The current left 
margin changes when nested lists are formatted. 

If there is an information source containing the 

LINES, FIG, or XMP tag imbedded at various 

locations, including within lists, it may not look the 

same each time. 


FIG, FIGCAP Tags 


FIG (Figure) 


>>—:FIG | 
RULE 
FRAME= L None 


>—:EFIG. 


-figure-content 


LeFTECAP. Flodreceapetanntext—_ 


>< 


The figure (FIG) tag identifies a diagram, chart, or 
other illustration. This tag requires a matching 
end tag. The figure tag is only allowed in informa- 
tion areas and help areas. A figure can also 
contain a figure caption, which is identified by the 
figure caption (FIGCAP) tag. 


Figures turn off automatic formatting, so the text is 
formatted the same way it is entered. The figure 
formats where it is entered, across the full width of 
the screen or window. 


Care should be taken when using figures within 
lists, because figure text that does not fit on one 
line wraps to column one of the next line. 


Figures are always formatted with the left margin 
set to column 2. The formatting width is two 
columns less than the width specified on the help 
module. When the FIG tag appears in an informa- 
tion area, the formatting width initially is two bytes 
less than the width specified on the panel tag. 


The figure caption begins at the left margin. 
There are two spaces between the figure tag, 
"Figure:", and the figure caption text if either the 
figure tag or the figure caption text are single-byte 
characters. There are four spaces between the 
figure tag and the figure caption if both are 
double-byte characters. If the figure caption does 
not fit on one line, it wraps onto the second line 
starting at position 4 relative to the left margin. 


Optional Attribute 


FRAME=RULE | NONE 
The type of frame to put around the figure. 
RULE is the default. A row of hyphens is dis- 
played above and below the figure. 


NONE indicates that no frame is used; a blank 
line is placed ahead of and behind the figure. 


Optional Tag 


FIGCAP. figure caption text 
A caption for the figure, if needed. The 
caption may appear on more than one line in 
the source. The FIGCAP tag must appear 
immediately before the EFIG tag. 


Example: Sample Figure 


This example shows how text formats the way it is 
entered with a FIG tag, and how a FIG tag can 
specify a frame to set the figure off from the rest 
of the text. 


UIM Source 


:FIG frame=rule. 
some 
sample 
text 
:FIGCAP.A Sample Figure 
:EFIG. 


Results 


some 
sample 
text 
Figure: A Sample Figure 
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HELP Tag 


HELP (Help Module) 


p>—: HELP—NAME=help-module-name 


Vy! 
oe eee el! 


> 
Igy! 
eel eee 


Lspatperieiestext= 


: EHELP. >< 


The help module (HELP) tag indicates the begin- 
ning of a help module. An EHELP tag must be 
specified at the end of the help module. A help 
module can be used for help displays and for 
index search topics. For more information on the 
index search function, see “ISCH (Index Search)” 
on page A-70. Help modules may also be linked 
to each other. For more information on how help 
modules may be linked together, see “LINK 
(Hypertext Link Definition)” on page A-78. 


Any tag that has a HELP attribute may refer to this 
module. 


Required Attribute 


NAME=help-moadule-name 
The name of this help module. For more 
information on the rules for naming, see 
“Name Syntax” on page A-4. 


This name can be referred to from: 


e The HELP attribute on UIM panel definition 
tags. 

e The NAME attribute on an import (IMPORT) 
tag. 


e The NAME attribute on an imbed help 
(IMHELP) tag within another help module. 


e The TOPICS attribute on an index search 
subtopic (ISCHSUBT) tag. 


e¢ The HLPPNLGRP keyword in data 
description specifications (DDS) specifica- 
tions. 


¢ Acontrol language (CL) command defi- 
nition. 


e The help identifier array parameter on the 
Display Help (QUHDSPH) API. 


¢ The DSPHELP dialog command. 
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The maximum length of the value for the NAME 
attribute is 32 characters. A slash (/) can be 
used in the name as a delimiter or separator 
character. The slash is used to separate a 
command name from a parameter name when 
naming a help module for commands. If the 
slash is used, the name must be enclosed in 
apostrophes ('). Help modules may not be 
nested. 


Optional Attributes 


WIDTH=" | help-window-depth 
The width of the help window when it is dis- 
played. A value specified for the WIDTH attri- 
bute must include 2 bytes of space for the 
right and left margin. The minimum width is 
32 bytes, and the maximum width is 74 bytes. 


Help modules that are displayed as full screen 
or in an extended help window are indented 
by 4 bytes. Therefore, the formatting width is 
6 bytes less than the width. For example, a 
help module formatted with the maximum 
width of 74 bytes has a formatting width of 68 
bytes. 


The UIM does not increase or decrease the 
width of the window if a value other than ™' is 
specified. The width should be specified only 
if the text between the HELP and EHELP tags 
depends on a window of a particular width. 


If the help is for the function keys or a list 
area and if WIDTH="', the UIM uses a width of 
38 bytes. If the help is for a menu area or 
data area, the UIM uses a width of 60 bytes. 
The UIM finds a location for the window using 
this width, then expands the window to a size 
which displays the online information in the 
most appropriate fashion. 


The width used is that of the first HELP tag 
found when the UIM assembles the online 
help information. 


DEPTH="™" | help-window-depth 


The depth of the help window when it is dis- 
played. The value specified for the depth may 
not be less than nine lines, and must include 
the following: 


¢ One line for a help title 

¢ One line for a top separator line 
¢ One line for a bottom separator 
e Two lines for the function keys 
¢ One line for the message line 


For help displayed in a pop-up window, the 
maximum value for the DEPTH attribute is 21. 


The UIM does not increase or decrease the 
depth of a window if a value other than ™' is 
specified. A specific depth should be speci- 
fied only if the text between the HELP and the 
EHELP tags depends on a particular window 
width. 


If the help is for a data area, menu area, or 
the function keys, and if DEPTH="*', the UIM 
chooses a depth of 9. If the help is for a list 
area, the UIM chooses a depth of 14. The 
UIM finds a location for the window using this 
depth, then expands the window to a size 
designed to display the online help information 
in the most appropriate fashion. 


The depth used is that of the first HELP tag 
found when the UIM assembles the online 
help information. 


Optional Text 
help-title-text 


The title used on the help panel. The text 
must appear on the same or next line as the 
tag and can only contain the reverse text (RT) 
tag. If the help-title-text is longer than the 
pop-up window width, the title text is truncated 
to the width of the pop-up window. If the 
value for the WIDTH attribute on this tag is 
greater than 57 or equal to ™', the maximum 
length of the help-title-text is 55 characters. 
Otherwise, the maximum length is the value 
specified for the WIDTH attribute minus two. 


The help panel title displayed depends on 
whether contextual or extended help is 


HELP Tag 


requested and whether the help is displayed 
as a full screen or in a pop-up window. 


Help information presented in pop-up windows 
is titled as follows: 


e For contextual help, the title of the HELP 
tag for the associated item is used. If no 
title is defined on the HELP tag, a default 
title of "Help" is used. 


e For extended help, the title from the first 
HELP tag for the panel is used. If no title 
is defined on the HELP tag, the default 
title or the full display title of the 
QUHDSPH API is used. 


If the text for the help title is longer than the 
pop-up window width, the title text is truncated 
at a word boundary to the width of the pop-up 
window. The default title or the full display 
title of the QUHDSPH API is used. 


Help information presented in full screen 
mode is titled as follows: 


e For contextual help, the title from the 
HELP tag is used. 


e For extended help, the title from the first 
HELP tag is used. 


e If no title is defined on the HELP tag, the 
default title or the full display title of the 
QUHDSPH API is used. 


Help modules must be coded so that each module 


can 


be individually formatted. Help modules must 


begin with one of the following tags: 


DL Definition list 

FIG Figure 

H1-H4 Headings 
IMHELP _ Imbed help 

ISCH Index search 
LINES Unformatted lines 
NT Note 

OL Ordered list 

P Paragraph 
PARML Parameter list 
SL Simple list 

UL Unordered list 
XH1-XH4_ Extended help headings 
XMP Example 
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A-61 


HELP Tag 


Example: Help Panel Definition 


This example shows how a help panel is defined 
and how the text is displayed. 


UIM Source 


shelp name=hmain.Main System Menu - Help 
ps 
This panel allows you to ... 

(extended description of the panel) 
:ehelp. 


Results 


[ | 
HELP Main System Menu 


This panel allows you to ... 
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HPO through HP9 Tags 


HPO through HP9 (Highlighted Phrase) 


>> sHPO. 


:HP1. Ered > EHP1. 
:HP2. ees :EHP2. 
:HP3. aol :EHP3. 
:HP4. aa > EHP4. 
:HP5. ae > EHP5. 
:HP6. Ea > EHP6. 
:HP7. peel > EHP7. 
:HP8. Bae :EHP8. 
:HP9. era :EHP9. 


>< 


These highlighted phrase (HPO-HP9Y) tags identify 
a word or phrase which is highlighted. All HPn 
tags require matching end tags. These tags are 
only allowed in help areas and in information 
areas that are not in the print head (PRTHEAD) or 
print panel (PRTPNL) tags. 


The HPn and EHPn tag phrase should be speci- 
fied on word boundaries. If the two characters 
immediately following the EHPn tag are a punctu- 
ation mark and a blank, the UIM automatically 
extends the emphasis attribute to include the 


punctuation mark. This allows the punctuation 
mark and the text associated with it to be dis- 
played using the same emphasis. 


Highlighting tags may be nested. For example, 
:HP1.text:HP2.text2:EHP2.text3:EHP1. is valid. 


Optional Text 


text 
Although the word or phrase to be highlighted 
is not required, the tag has no meaning when 
no text is specified. 
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HPO through HP9 Tags 
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Tag Color Device Formatting Monochrome Device Formatting Print Formatting 
For Help 

HPO Green Normal Normal 

HP1 Green, underscored Underscored Underlined 

HP2 White High intensity Bold 

HP3 White, underscored High intensity, underscored Bold, underlined 

HP4 Green Normal Normal 

HP5 Underlined 

HP6 Underlined 

HP7 White, reverse image High intensity, reverse image Bold, underlined 

HP8 White, reverse image High intensity, reverse image Bold, underlined 

HP9 MOINES UCAETETE Wine Te Underlined 

RV2W062-0 


H1 through H4 Tags 


H1 through H4 (Heading) 


>> :H1 -heading-text 
:H2 
:H3 
:H4 


>< 


The heading (H1-H4) tags identify main topics and 
subtopics of information. These tags are only 
allowed in information areas and help areas. 


In a help area, text after the headings is indented 
four spaces from the margin to separate the 
headings from the text. In an information area, 
text formats flush left, against the left margin. 


Headings have one blank line formatted before 
and after the heading text. 


Specific formatting rules are as follow: 


H1 Centers and formats text as underscored and 
highlighted, like the HP3 tag. This tag 
causes a page eject when it appears ina 
printed help module. 


H2 Left justifies and formats text as underscored 
and highlighted, like the HP3 tag. 


H3 Left justifies and formats text as highlighted 
text, like the HP2 tag. 


H4 Left justifies and formats text as under- 
scored, like the HP1 tag. 


Required Text 


heading-text 
The text for the heading. The text of a 
heading must be entered on a single line and 
is formatted as entered. It cannot contain any 
other tags. A common practice is to enter the 


text according to the current publishing style, 
with significant words in initial caps. 


Example: Heading Tags 


This example illustrates how the different headings 
are justified and formatted. 


UIM Source 


:H1.A One Heading 

:p.Here's a paragraph. 
:H2.A Two Heading 
:p.Another paragraph. 

:H3.A Three Heading 
:p.Still another paragraph. 
:H4.A Four Heading 

:p.Still another paragraph. 


Results: 

A One Heading 

Here's a paragraph. 

A Two Heading 
Another paragraph. 

A Three Heading 

Still another paragraph. 


A Four Heading 


Still another paragraph. 


Appendix A. UIM Panel Group Definition Language A-65 


IMHELP Tag 


IMHELP (Imbed Help) 


p>>—: IMHELP—NAME=he 1 p-module-name 


>< 


The imbed help (IMHELP) tag embeds a help 
module from another panel group object. This tag 
can occur only in help modules within the help 
module (HELP) and EHELP tags. 


Required Attribute 


NAME=help-moadule-name 
The name of a help module imbedded where 
this tag occurs. For more information on the 
rules for naming, see “Name Syntax” on 
page A-4. The name must be the name of 
another help module defined within the same 
panel group, or it must be imported from 
another panel group using the import 
(IMPORT) tag. IMHELP tags have a nesting 
limit of 16. 


If the index search (ISCH) or index search 
synonym (ISCHSYN) tags are a part of the 
embedded help module, they are not part of 


the module where the the IMHELP tag occurs. 


An active highlight phrase (HPn) tag is not 
allowed when an IMHELP tag is coded. Any 
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active HPn tags must be ended with EHPn 
tags before coding the IMHELP tag. 


Example: Imbedded Help 


This example uses imported help for the help on 
function keys. 


UIM Source 


:HELP name='menul'. 
:H2.Purpose of MENU1 
Menul is intended for the use of... 


: IMHELP name='keydefs'. 
:EHELP. 


:HELP name='keydefs'. 
:PARML. 

:PT.F1=Help 

:PD.This key... 
:PT.F3=Exit 

:PD.This key... 
:EPARML. 

:EHELP. 


IMPORT Tag 


IMPORT (Import) 


>>—: IMPORT—NAME= enBOREEG=NGMe 7 ,—antuan’ panel Grolp=none > 
| Vy! 
> | J - >< 
I SAME PRDLIB=product-library-name 
NEWNAME=——private-name 


The import (IMPORT) tag makes help modules 
defined in another panel group object available in 
the current panel group. This tag must appear in 
the prolog section of the panel group source fol- 
lowing the panel group (PNLGRP) tags and the 
copyright (COPYR) tag. An IMPORT tag must be 
specified before any references by other tags to 
the help modules it defines. 


This tag may also assign a private name to the 
imported help module. If a private name is 
assigned, the private name replaces the imported 
name in the scope of the current panel group. 
This allows names to be imported that would have 
conflicted with other names within the current 
panel group. 


Required Attributes 


NAME=/mported-name | '*' 
The internal name of the help module 
imported for use within the current panel 
group. For more information on the rules for 
naming, see “Name Syntax” on page A-4. 


If '*' is coded, all unresolved names are 
assumed to be imported from this panel 
group. Only one IMPORT tag may be coded 
with NAME='*'. 


PNLGRP=panel-group-name 
The name of the panel group that contains the 
help module specified by NAME. This is an 
OS/400 object name which obeys all object 
name rules. This name may be fully qualified. 


Optional Attributes 


NEWNAME=SAME | private-name 
A new name used instead of the imported 
name within the current panel group. The 
new name suppresses the visibility of the 
imported name and serves as its replacement. 
Only NEWNAME=SAME is allowed when 
NAME='*' is specified. 


PRDLIB=product-library-name 
The name of the library added into the library 
search list as a product library, used to locate 
the panel group defining the help module 
specified by the NAME attribute on this tag. 
This attribute is not allowed when the PNLGRP 
attribute is fully qualified. 


The product library is only used when imbed- 
ding help information using the imbed help 
(IMHELP) tag. The product library is ignored 
when referring to a help module using the 
HELP attribute on other UIM tags. 
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INFO Tag 


INFO (Information Area) 


;—— Syntax for Display Panels 


RULE 


>>—: INFO—DEPTH=——area-depth > 
ie panacea q SPACE | | ale 
BOTSEP= vone— SCROLL=——YES 
RULE 
> :EINFO. >< 
preg tiles 
;—— Syntax for Print Panels 
>>—: INFO aa = : EINFO, >< 
I SPACE | | Real area-title 
BOTSEP= vone— TYPE=——PROLOG 


An information area (INFO) tag provides textual 
information to explain the operation of an applica- 
tion or panel. This tag is allowed for display 
panels and print panels. It can construct a 
detailed instruction area on a panel. 


Information areas are formatted with a width of 72 
columns unless the width attribute on the panel 
tag is less than 74 columns. In this case, the 
information area is formatted with a width of two 
columns less than the width attribute on the panel 
tag. 


Required Attribute 


DEPTH=area-depth | '*' 
The depth of the area in lines, including sepa- 
rators if any are specified. This attribute is 
required for display panels, but not allowed for 
print panels. If '*' is specified, the space 
remaining on the display after other panel ele- 
ments are allocated is given to this area. 
Only one area in the panel may have !*' 
coded. 


Optional Attributes 


BOTSEP=SPACE | NONE | RULE 
Defines the bottom separator for the informa- 
tion area. If SPACE is specified, a line of 
spaces is used. 


NONE indicates that no separator line exists. 
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If RULE is specified, a line of underscored 
spaces is used. 


SCROLL=NO | YES 
Indicates whether or not this area is scrollable. 
This attribute is allowed only for display 
panels. NO indicates that the area is not 
scrollable. 


YES indicates that the area is intended to be 
scrollable. For a SCROLL=YES area, a line of 
spaces is used by the UIM to provide a line 
for the scroll information. If BOTSEP=SPACE is 
specified also, one line is used for both the 
separator and the scroll information line. 


TYPE=NORMAL | PROLOG 
Indicates whether or not this information area 
is a prolog area. The prolog area is printed 
only once after the title line on the first page. 
This attribute is allowed only for the print head 
(PRTHEAD) tag. This attribute is valid only 
when the INFO tag appears between the 
PRTHEAD and the EPRTHEAD tags for infor- 
mation areas in a PRTHEAD panel. NORMAL 
is the default value. 


Optional Text 


area-title 
The title of the area. If no text is specified, no 
title line is allocated to the area. The text 
must appear on the same or next line as the 
tag, can contain only the reverse text (RT) 


INFO Tag 


tag, and cannot exceed a maximum length of tion areas are formatted to a width of 72 columns, 
55 characters long. as is done for information areas on display panels, 
regardless of the width specified on the PRTHEAD 

Print Formatting Considerations or print panel (PRTPNL) tag. 


Printed information areas are formatted like dis- 
played areas, except when four lines of an infor- 
mation area do not fit on a page when printing. If 
this is the case, a page eject occurs and the infor- 
mation area is printed on the next page. Informa- 
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ISCH Tag 


ISCH (Index Search) 


p>>—: ISCH—ROOTS='root-word-list '—.—index-entry-text >< 


The index search (ISCH) tag identifies the text dis- 
played by the index search function if the user 
enters a word that matches a synonym. The 
ISCH tag is only allowed in source code for panel 
group objects and is not allowed in the source for 
menu objects. The placement of the ISCH tag 
determines the help module displayed when the 
index entry is selected. The ISCH tags should 
appear immediately after the help module (HELP) 
tag it refers to. 


Required Attribute 


ROOTS='root-word-list' 
A list of up to 50 root words that apply to the 
index entry. Each root word may be up to 20 
characters and can contain only the charac- 
ters A through Z, a through z, and 0 through 
9. One or more blanks must be specified 
between words, so the entire list must be 
enclosed in apostrophes. The ROOTS attribute 
may be repeated, allowing you to define more 
root words for an index entry than fits on one 
source line. 


The root words serve as a link between the 
ISCH tags and the index search synonym 
(ISCHSYN) tags, and do not appear to the 
user. To allow the user to search for an index 
entry, each root word specified here must 
have a matching root word on an ISCHSYN 
tag. 


Required Text 


index-entry-text 
The text of the index entry presented when 
one of the synonym words is selected. The 
text may contain up to 72 characters but can 
not contain other tags. It must appear on the 
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same or next line as the period which ends 
the tag definition and cannot span two lines in 
the source. 


If the index entry is a subtopic, the index- 
entry-text is indented two spaces from the text 
of the first higher index entry in the hierarchy 
of index entries. 


The text which is provided is used as the topic 
title when topics are presented for selection. 
If no text is specified on the HELP tag of the 
topic, the text provided on the ISCH tag is 
also used as the panel title when the topic is 
selected for presentation. When used as a 
panel title, no more than 55 characters of the 
text is shown. If the text contains more than 
55 characters, it is truncated at a blank and 
an ellipse (...) is placed after the text to indi- 
cate that truncation has occurred. 


Example: Index Search 


This example shows some ISCHSYN tags and the 
ISCH tags that use them: 


UIM Source 


: ISCHSYN ROOT='copy'.copy copying copies 

: ISCHSYN ROOT='delete'.delete deleting deletes 
: ISCHSYN ROOT='delete'.remove removes removing 
: ISCHSYN ROOT='folder'. folder folders 

: ISCHSYN ROOT='folder'.document documents 


:help name=fldcpy. 
:ISCH ROOTS='copy folder'.Copying folders 


:ehelp. 

shelp name=flddit. 

:ISCH ROOTS='delete folder’. 
Deleting folders 

:ehelp. 


ISCHSUBT Tag 


ISCHSUBT (Index Search Subtopic) 


p>>—: ISCHSUBT—TOPICS='help-module-name-list' >< 
The index search subtopic (ISCHSUBT) tag identi- UIM Source 
fies the help modules within the same panel group ; Seer 
that are subtopics under the preceding topic speci- ae Ce, 
fied on an index search (ISCH) tag. The Main sisi. Topic : 
ISCHSUBT tag must appear after the ISCH tag. SISCHSUBT topics='help1' 
This tag is repeatable. topics='help2'. 
Any help module with an ISCH tag that is not SEHELP. 
identified by an ISCHSUBT tag is a primary topic :HELP name=help1. 
in the index search hierarchy. Therefore, if no :ISCH roots='root words'. 
ISCHSUBT tags are used, all help modules are Help number 1 
primary topics and there is no hierarchy in the :ISCHSUBT topics='help3 help4'. 
index search. The ISCHSUBT tag is allowed only : 
in source code for panel group objects; it is not :EHELP. 
allowed in the source code for menu objects. :HELP name=help2. 
:ISCH roots='root words'. 
. . Help number 2 
Required Attribute :ISCHSUBT topics='help3' 
TOPICS= ‘help-module-name-list' : 
Identifies the help modules within the same sEHELP. 7 
panel group that are subtopics under the pre- eae ee ie 
ceding topic specified on an index search Hel Perea ee 
(ISCH) tag. The order in which the help et 
modules appear on the TOPICS attribute is -EHELP 
the order in which they are displayed in the “HELP nae=hel o4 
index search hierarchy. A help topic name eTSClrostee honk Worden: 
cannot be specified twice in this list. For more Help number 4 
information on the rules for help modules : 
names, see “Name Syntax” on page A-4. :EHELP. 
This attribute is repeatable. 
A topic can be the subtopic of more than one This UIM source creates the following index 
topic. search hierarchy: 
Topics can be nested to no more than 16 nls of ens HneeX 
vale Main Help Topic 
; Help number 1 
Help number 3 
Example: Index Search Help number 4 
Hierarch Help number 2 
y Help number 3 
The following example shows how the ISCH tags 
and ISCHSUBT tags work together to form an 
index search hierarchy: 
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ISCHSYN Tag 


ISCHSYN (Index Search Synonym) 


p>>—: ISCHSYN—ROOT=root -word—.—synonym-words 


>< 


The index search synonym (ISCHSYN) tag identi- 
fies the variations and synonyms for the root 
words used in the index search function. The 
ISCHSYN tag is only allowed in source for panel 
group objects and is not allowed in the source for 
menu objects. 


The text must be entered on one line. If more 
than one line is needed, multiple ISCHSYN tags 
may be coded. This text, when combined with the 
index search (ISCH) tag, determines the index 
entries displayed when the user enters words for 
the index search function. 


The ISCHSYN tags build a table of synonyms, 
which serves as a link to the ISCH tags. As 
words are entered for an index search, they are 
matched with the words in the synonym table to 
link to the entries displayed. 


There is no restriction on the placement of the 
ISCHSYN tags, but to make maintenance and 
translation easier, they should be placed in one 
area, such as the beginning of the panel group or 
in a panel group object which contains only 
ISCHSYN tags. 


Required Attribute 


ROOT=' root-wora' 
The root word to which the synonyms apply. 
If a real word is used for the root word, like 
“copy,” that word should also be entered in 
the synonym-words field. 


The root word is used in the ROOTS attribute of 
the ISCH tag and may be up to 20 characters. 
A root word can contain only the characters A 
through Z, a through z, and 0 through 9. 


Required Text 


synonym-words 
Special Format. Specifies variations and 
synonyms for the root word. The synonym 
words must be separated by blanks. If addi- 
tional synonyms are needed for a root word, 
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additional ISCHSYN tags should be entered 
specifying the same root word. The additional 
synonyms are added to the previous syno- 
nyms. 


Each synonym word must be 40 characters or 
less and can contain no spaces. It cannot 
contain a period, left or right parenthesis, a 
semicolon, a comma, question mark, or colon. 


Different languages have a larger or smaller 
number of synonyms for each word. To 
provide meaningful results, the translation of a 
root word must be done by providing a list of 
synonym words and by not translating each 
English synonym. 


The UIM automatically handles lowercase, 
single-byte character set (SBCS) synonym 
words the same way as uppercase words, 
using the code page specified on the TXTCHRID 
attribute of the panel group (PNLGRP) tag. 


Example: Index Search 
Synonyms 


This example shows several ISCHSYN tags and 
how they are referred to by ISCH tags. 


UIM Source 
:pnigrp... 


: ISCHSYN ROOT='copy'.copy copying 

:ISCHSYN ROOT='copy'.duplicate duplicating 
: ISCHSYN ROOT='copy' .model 

: ISCHSYN ROOT='root1'.remove removing 

: ISCHSYN ROOT='root1'.delete deleting 

: ISCHSYN ROOT='root1'.trash discard 

: ISCHSYN ROOT='folder'.folder folders 

: ISCHSYN ROOT='folder'.document documents 
: ISCHSYN ROOT='folder'.data information 


shelp name=fldcpy. 
:ISCH ROOTS='copy folder'.Copying a folder 
:h2.Copying a Folder 


:ehelp. 


shelp name=flddit. 
:ISCH ROOTS='rootl folder'.Deleting a folder 
:h2.Deleting a folder 


:ehelp. 


In this example, the ISCHSYN tags builds a 
synonym table containing the following entries: 


Root Word Synonym Words 


copy copy copying duplicate 
duplicating model 
root1 remove removing delete deleting 


trash discard 


ISCHSYN Tag 


folder folder folders document documents 
data information 


The ISCH tag for the “Copying a folder” entry 
points to the “copy” and “folder” search synonym 
lists. 


When the user requests "copy folders," the entry 
is found and displayed because "copy" and 
"folders" are both listed as matches in the 
ISCHSYN table. If the user entered "copy 
folders," "folders, copy," or "copying documents," 
the entry "Copying a folder" is displayed. 
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KEYI Tag 


KEYI (Key List Item) 


> 


p>—: KEY I—KEY=key-name—HELP=he 1 p-module-name 


LactIon= ‘action-text = 


> 


Lconp=condition-name—| I Sela LepptoRitvepriority_number—| 
VARUPD=——NO 


Legeysdesenipeionavert-. 


>< 


The key list item (KEYI) tag defines a single func- 
tion key. This tag must occur between the KEYL 
and EKEYL tags. It assigns displayable text for a 
specified key and identifies the action to take 
place when that key is pressed. 


Required Attributes 


KEY=key-name 
The names for the engraved or software 
defined function keys are Attn, Enter, F1-F24, 
Help, Home, Print, Pagedown, Pageup, and 
Sysreq. 


HELP=help-module-name 
The associated help module for the key 
description. The help module name may be a 
name imported from another panel group, but 
it must follow the rules for names outlined 
earlier in this chapter. For more information 
on the rules for naming, see “Name Syntax” 
on page A-4. 


ACTION=' action-text' 
The action occurring when the function key is 
pressed. This attribute is conditionally 
required. For certain keys, the ACTION attri- 
bute must not be specified since the UIM does 
not handle that particular key. For all other 
keys, the ACTION attribute is required. 


The valid forms of action text are: 


¢ ‘ACTIONS' 

¢ ‘CALL program-reference' 
For a description of the interface between 
the UIM and the function key CALL 
program, see the System API Reference. 

¢ 'CANCEL' 

¢ 'CHGVIEW' 

¢ ‘CMD commano-string' 
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Any dialog variable in the command string 
must be preceded by an ampersand to 
denote variable substitution. 

¢ 'CMDLINE' 

'ENTER' 

‘EXIT’ 

‘HELP’ 

'HOME' 

e ‘MENU qualified-menu-name 
RTNPNT/NORTNPNT' 

e MOREKEYS' 

¢ MOVETOP' 

e¢ 'PRINT' 

¢ 'PROMPT' 

e 'RETRIEVE' 

e 'RETURN positive-integer' 

¢ 'PAGEUP' 

¢ 'PAGEDOWN' 


For a description of each of these actions, see 
Appendix B, “UIM Dialog Commands’ on 
page B-1. 


Engraved key assignments are enforced by 
the compiler. These keys are the keys listed, 
except for F1 through F24. If engraved keys 
are assigned anything but their corresponding 
dialog function (or no action in certain cases), 
a compile error results. The following is a list 
of the engraved keys and their corresponding 
actions: 


Key Action 

Attn No action 
Enter 'ENTER' 

Help 'HELP' 

Home ‘HOME' 

Print 'PRINT' 
Pageup ‘PAGEUP' 
Pagedown ‘PAGEDOWN' 
Sysreq No action 


Optional Attributes 


COND=condition-name 


The key is in effect on the panel only if the 
condition specified is true. The condition must 
be defined in the panel group with the condi- 
tion definition (COND) tag. 


VARUPD=YES | NO 


If YES is coded, validity checking occurs and 
the variable pool is updated with values 
entered by the user before the action takes 
place. 


If NO is coded, the action is performed imme- 
diately and no variable pool updating occurs. 
If the VARUPD attribute is not specified and the 
EXIT or CANCEL dialog command is specified 
on the ACTION attribute of this tag, a warning 
message is generated at compile time stating 
that VARUPD=YES is assumed. This is done as 
a reminder to you, because you may not want 
to check for valid input data before allowing 
the user to exit a screen through these dialog 
commands. To avoid this message, specify 
VARUPD=YES or VARUPD=NO on the key assign- 
ment. 


If no ACTION attribute is specified, this attribute 
is ignored. 


PRIORITY=priority-number 


The order in which keys should be displayed 
when the MOREKEYS dialog command is 
performed. 


Key items with a lower number priority are dis- 
played before key items with a higher number 
priority. A specified priority number must be 
greater than or equal to one and less than or 
equal to 99. 


If a priority is not specified for a key, the 
default value depends on the action specified: 


Action Default 
EXIT 1 
CANCEL 2 

All others 99 


No action 99 


The PRIORITY attribute is used only within a 
key list that has ACTION>MOREKEYS speci- 


KEYI Tag 


fied on one of the KEYI tags. Otherwise, the 
priority attribute is ignored. 


Optional Text 


key-description-text 
The displayable description for the associated 
key. For example, "F5=Refresh" or 
"F12=Cancel". If no text is specified, a 
description of the key is not displayed on the 
panel, although the key is active. The text 
must appear on the same or next line as the 
tag and can only contain the reverse text (RT) 
tag. 


The function key area is formed by concat- 
enating the text from the various key list 
items, with each key separated by at least 
three spaces. If the text does not fit on the 
rest of a line, it is placed on the next line. 


Example: Key Definitions 


The following example defines the function keys 
F3, F5, F11, and F12. 


UIM Source 


:keyl name=keylist 
help=hkeylist. 

skeyi key=f3 
action='exit set' 
help=exit 
.F3=End task 

skeyi key=f5 
action='return 5' 
help=refresh 
.F5=Refresh 

:keyi key=f11 
action=chgview 
help=chgview 
.F1l=Alternate view 

&gms.keyi key=f12 
action='cancel set' 
help=cancel 
.F12=Cancel 

:ekeyl. 


Results 


L F3=End task F5=Refresh F1l=Alternate view F12=Cancel 
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KEYL Tag 


KEYL (Key List) 


>>—: KEYL—NAME=key-list-name 


EU Shel anédute=nane—| 


:EKEYL. > 


The key list (KEYL) tag indicates the beginning of 
a list of key definitions. Each list may be referred 
to by one or more panel definitions. An EKEYL 
tag must be specified at the end of the key list. 


Other tags can be nested within the KEYL tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 
appear and specifies on which page more infor- 
mation can be found for each tag. 


Table A-8. Tag Allowed Between the KEYL and 
EKEYL Tags. 


Tag Name Order Page 


KEYI 1 A-76 
(Key list item) 


Required Attribute 


NAME=key-list-name 
The name assigned to the key list. For more 
information on the rules for naming, see 
“Name Syntax” on page A-4. 


Optional Attribute 


HELP=help-module-name 
Identifies online help information explaining 
the purpose of the function keys. The name 
of the help module can be a name imported 
from another panel group, but must follow the 


rules for names outlined earlier in this chapter. 


For more information on the rules for names, 
see “Name Syntax” on page A-4. 
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Example: Key List 


This is an example of a key list. 


UIM Source: An example of a key list follows: 


:keyl name=keylist. 

:keyi key=f1 
help='key/helpf1' 
action=help. 

:keyi key=f3 
help='key/exit' 
action='exit set'.F3=Exit 

:keyi key=f12 
help='key/cancel ' 
action='cancel set'.F12=Cancel 

:keyi key=f24 
help='key/morekeys ! 
action=morekeys.F24=More keys 

:keyi key=enter 
help='key/enter' 
action=enter. 

:keyi key=help 
help='key/help' 
action=help. 

:keyi key=pagedown 
help='key/pagedown' 
action=pagedown. 

:keyi key=pageup 
help='key/pageup' 
action=pageup. 

:keyi key=print 
help='key/print' 
action=print. 

:ekeyl. 


LINES Tag 


LINES (Unformatted Lines) 


p>>—:LINES. 
Lainformatvedsi mes 


:ELINES. 


>< 


The unformatted lines (LINES) tag identifies an 
area of user-controlled line entry where the lines 
are not automatically concatenated. Text is for- 
matted the same way it is entered. This tag is 
only allowed in information areas and help areas. 
The LINES tag requires a matching end tag. 


Note: Care should be taken when using unfor- 
matted lines within lists, because text that does 
not fit on one line wraps to column one of the next 
line. The current left margin changes when 
nested lists are being formatted. If there is online 
help information containing unformatted lines 
imbedded at various locations, including within 
lists, it may not look the same each time. 


Help modules displayed in full-screen format or in 
an extended help window are indented by 4 bytes. 
Therefore, the formatting width initially is 6 bytes 
less than the width specified on the help module. 
When the LINES tag appears in an information 
area, the formatting width initially is two bytes less 
than the width specified on the panel tag. 


Optional Text 


unformatted-lines 
Although the text for the unformatted lines is 
not required, the tag has no meaning when no 
text is specified. 


Example: Unformatted Lines 


This example illustrates how text is formatted the 
same way it is entered. 


UIM Source 


:LINES. 
First line 
Second line 
:ELINES. 


Results 


First line 
Second line 
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LINK Tag 


LINK (Hypertext Link Definition) 


>>—:LINK—PERFORM='‘action-text ' a > 
UNLESS1—+—= 'conditional-expression' 
UNLESS2 
UNLESS3 
UNLESS4 
> > 
THENDO1 “idcrion-texe!— Lo iNiwENS*condéPtonal expression’! 
THENDO2 
eal 
THENDO4 
> :ELINK. | 
Layereciennrase- 


The hypertext link definition (LINK) tag identifies 
the reference phrase text which is the anchor of a 
static hypertext link. A reference phrase may 
appear in any UIM help area, but may not appear 
in an information area. This tag requires a 
matching end tag. It also identifies action taken 
when the reference phrase is selected. The only 
type of action supported is to display a help 
module. 


The LINK and ELINK tag must be specified on 
word boundaries. If the two characters imme- 
diately following the ELINK tag are a punctuation 
mark and a blank, the UIM automatically extends 
the emphasis attribute to include the punctuation 
mark. This allows the punctuation mark and the 
text associated with it to be displayed using the 
same emphasis. 


On a monochrome device, the reference phrase 
text is displayed as highlighted, underscored text. 
On a color device, the reference phrase text is 
displayed as underscored, yellow text. Because 
of hardware limitations, the underscore is not 
visible on a PS/2* computer or on a personal com- 
puter with a color device. 


The only tag that can be used within a link tag is 
the reverse text (RT) tag. LINK tags may not be 
used within other LINK tags, but may be used 
within any of the following tags: 


CIT Title citation 

DD Definition 

FIG Figure 

FIGCAP Figure caption text 
HPn Highlighted phrase 
LI List item 
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LINES Unformatted lines 

LP List part 

NT Note 

P Paragraph 

PC Paragraph continuation 
PD Parameter description 

PK Programming keyword 
PV Programming variable 

XMP Example 


Required Attribute 


PERFORMZ=' action-text' 
The action occurring when the reference 
phrase is selected and all of the condition 
expressions for the UNLESSn attributes have 
evaluated to false. The valid form of action 
text is: 


¢ 'DSPHELP help-module-name [| panel- 
group-name |' 


Note: The brackets in the action text above 
indicate that the panel group name is optional. 
They are not required in the UIM source. 


For a description of the DSPHELP action, see 
Appendix B, “UIM Dialog Commands” on 
page B-1. 


Optional Attributes 


UNLESSnz=' conditional-expression' . 
The only allowed values for n are 1 through 4. 


The UNLESSn and THENDOn attributes must be 
coded as pairs. The expressions on the 
UNLESSn attributes are evaluated in numeric 
order. If one evaluates to true, the corre- 


sponding THENDOn action is performed and all 
higher-numbered UNLESSn and THENn attributes 
and the PERFORM attribute on this tag are 
ignored. 


For information on using conditional 
expressions with the UNLESSn attribute, see 
“Conditional Expressions.” 


THENDOnz=' action-text' 
The only allowed values for n are 1 through 4. 


This attribute specifies the action occurring 
when the reference phrase is selected and the 
conditional expression for the corresponding 
UNLESSn attribute evaluates to true and all the 
conditional expressions for the lower- 
numbered UNLESSn attributes evaluate to false. 


The UNLESSn and THENDOn attributes must be 
coded as pairs. The UNLESSn attributes are 
evaluated in numeric order. If one evaluates 
to true, the corresponding THENDOn action is 
performed and all higher-numbered UNLESSn 
attributes and the PERFORM attribute on this tag 
are ignored. 


The valid form of action text is: 


¢ 'DSPHELP  help-module-name [| panel- 
group-name ]' 


Note: The brackets in the option text above 
indicate that the panel group name is optional. 
They are not required in the UIM source. 


For a description of the DSPHELP action, see 
Appendix B, “UIM Dialog Commands” on 
page B-1. 


LINKWHEN=' conditional-expression' . 
When the LINKWHEN expression evaluates to 
true or is not coded, the reference phrase is 
made available and a user is allowed to select 
it. When the LINKWHEN expression evaluates 
to false, the reference phrase is not activated 
and may not be selected. 


For more information on using conditional 
expressions with the LINKWHEN attributes, see 
“Conditional Expressions.” 


LINK Tag 


Conditional Expressions 


Although the set of conditions that can be formed 
with the LINKWHEN attribute is identical to the set of 
conditions that can be formed with the UNLESSn 
attributes, the significance of those conditions is 
different. The LINKWHEN attribute activates or 
deactivates the LINK tag, while the UNLESSn attri- 
bute selects the action performed when an active 
LINK tag is selected. A conditional expression is 
a true or false expression in the following form: 


* AND 
non | 
>> ! ‘ A | >< 


— 
*NOT (A) 


where A is an operand which can be one of the 
following: 


¢ Aconditional expression 
¢ A built-in function 


The logical OR character (|) can be used in place 
of “OR, the ampersand character (&) can be used 
in place of “AND, and the logical NOT character 
(=) can be used in place of *NOT. Because the 
logical OR and logical NOT characters are not in 
the invariant character set, their use is not recom- 
mended. For code page 00037, the common USA 
code page, the hexadecimal value of the logical 
OR character is X'4F', and the hexadecimal 
value of the logical NOT character is X'5F'. The 
UIM compiler uses these hexadecimal values 
regardless of the code page of the source. 


There are two built-in functions: 


CHKOBJ 
Evaluates to true if the object is found on the 
system and the current job possesses at least 
the level of authorization to the object speci- 
fied by the authorities. Arguments must be 
character strings enclosed in double quotation 
marks ("). The object name follows OS/400 
object naming conventions. The object type is 
any of the allowable object types for the 
DSPOBJD command and the authorities must 
be a single value or a list of authorizations to 
be checked for. The values of these authori- 
zations are separated by blanks. The fol- 
lowing syntax diagram illustrates the 
authorities and how to use them: 
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LINK Tag 


»>—CHKOBU (——obj-name ,—"obj-type"-——> Examples of conditional expressions follow: 
Nant enamet! 

> ) >< CHKOBJ ("OBJECT", "*FILE", "*USE") 

,—"—-* CHANGE : 
*ALL CHKOBJ ("PANELGRP","*PNLGRP") 
ce *AND CHKUSRCLS ("*PGMR") 
ps CHKOBJ ("DOCUMENT","*DOC","*READ *UPD") 
*OR CHKUSRCLS ("*SYSOPR") 


*NOT (CHKOBJ ("PROGRAM" ,'"*PGM") ) 


Bidirectional Considerations 


The value of the BIDI attribute on the panel group 
(PNLGRP) tag of all possible panel groups that 
can be reached by taking hypertext links should 
be the same. If they are not the same, it is pos- 
sible that the resulting screen or pop-up window is 


displayed with the opposite orientation when a ref- 
If no authorities are specified, no authorization erence phrase is selected. 


check is performed and the function becomes 
an existence check. 


Note: 
' Each value can be used only once, a 
maximum of 7 


Example: Hypertext Link 


When a program adopts the authority of its 


owner, that authority is normally used to This example shows how hypertext links can be 
authorize operations performed by that used to provide definitions for terms. 

program. However, when help is requested, 

those adopted authorities are ignored while UIM Source 


the UIM displays the online help information. 
Therefore, no adopted authorities are used 
when the CHKOB4g function is used on the 
UNLESS or LINKWHEN attributes on the 


:HELP NAME='hyper/help' .Hypertext in 0S/400 

:P. 

Hypertext lets users explore 

the online help information in a way that is most 


LINK tag. natural for them. 

For more information about programs adopting Hypertext links can be used within :LINK 
the authority of the owner, see the PERFORM='DSPHELP item/specific/help' 
USRPRF(*OWNER) parameter on the ete Speer ive. DelpeE EINK: 


:LINK PERFORM='dsphelp extended/help' 


Cale iheommeane: -extended help:ELINK., and 


CHKUSRCLS :LINK PERFORM='dsphelp index/search' 
The user class argument specified for the -index search help:ELINK.. 
function is compared to the user class param- :EHELP. 


eter from the user profile of the current job. 
The function evaluates to true if the user 
profile has the same or greater value than the 


:HELP NAME='item/specific/help' 
.Definition of Item Specific Help 


. alae 
function argument. The function argument Item specific help is . 
must be enclosed in double quotation marks EHELP. 
("). 
The following syntax diagram illustrates the sHELP NAME='extended/help' 
valid argument values for the user class: - -Definition of Extended Help 
>> —CHKUSRCLS (—*SECOFR——) ne Extended help is... 
*SECADM - EHELP 
* PGMR ° ° 
ae :HELP NAME='index/search' 
.Definition of Index Search 
eR 
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Index search allows you to tell the 

system to search for specific information. 

Index search information is made more 

useful by the addition of 

:LINK PERFORM='dsphelp hyper/help' 
-hypertext:ELINK. because 

it allows you to link to additional help 

topics. 

:EHELP. 


Results 


LINK Tag 


Hypertext on 0S/400 


: Hypertext lets users explore the online information in a way 
: that is most natural for them. Hypertext links can be used 
: within item specific help, extended help, and 

: index search help. : 


: Bottom : 
: F2=Extended help F10=Move to top Fll=Index search * 
: F12=Cancel F13=User support F24=More keys 


When the cursor is moved to INDEX SEARCH 
HELP and the Enter key is pressed, the following 
screen is shown. 


Definition of Index Search 


: Index search allows you to tell the system to search for specific : 
: information. Index search information is made more useful by the : 
: addition of > hypertext because it allows you to link to . 
: additional help topics. 


7 Bottom : 
: F6=Viewed topics F10=Move to top Fll=Index search : 
: F12=Cancel F13=User support F24=More keys 
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LIST Tag 


LIST (List Area) 


The list area (LIST) tag defines a list area on a 
panel. 


This tag is allowed for display panels and print 
panels, except for the print head panel 
(PRTHEAD) tag. A list area consists of an arbi- 
trary number of rows of like columns, and can be 
scrolled up and down if the number of rows 
exceeds the area in which the list is displayed. 


A list area presents a view of a UIM list, which is 


manipulated by the UIM application programming 
interfaces (APIs). UIM lists are named and 
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;-—— Syntax for Display Panels 
>>—: LIST—DEPTH= ge one ay sno eee Meee iiamie > 
‘x! | SPACE | 
BOTSEP= vone— 
RULE 
> > 
i el | | 0 i SPACE 
SCROLL= MAXHEAD=—7—1 BODYSEP=—— INDENT 
2 BOTH 
3 NONE 
4 
VIEW=dialog-variable-name | NONE | | aie 
ACTOR=—;—-UIM EXTACT=——YES 
CALLER 
> > 
I NONE | | 2 Lbapnsoalologevariableshane=! 
SELECT=—7—S INGLE maxacTL=—[-1 
MULTI 3 
> :ELIST. >< 
Lae ADSize-diglogevaniabresnane| Lencuuainies! 
;—— Syntax for Print Panels 
p>>—: LIST—LISTDEF=list-name > 
| smack | 
BOTSEP= vone— MAXHEAD=——1 
RULE 2 
3 
4 
SPACE VIEW=dialog-variable-name 
BODYSEP=—— INDENT 
BOTH 
NONE 
> :ELIST. >< 
Lueapsize- =dialog-variable- aaa! Pospeat title 


described by the list definition (LISTDEF) tag. 
The UIM displays the entries in the list, handling 
the scroll operations which allow the user to see 
all the entries. 


The area may have multiple views, which are 

selected by the CHGVIEW dialog command. The 
CHGVIEW dialog command can be assigned to a 
function key which alternates between the views. 


Other tags can be nested within the LIST tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 


appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-9. Tags Allowed Between the LIST and 
ELIST Tags 


Tag Name Order Use Page 


TOPINST 1 D A-161 
(Top instruction 
line) 


LISTACT 2 D A-90 
(List action) 


LISTGRP 3 B A-103 
(List column 


group) 


LISTCOL 3 B A-96 
(List column) 


LISTVIEW 4 B A-105 
(List view) 
BOTINST 5 D A-10 


(Bottom instruc- 
tion line) 


Required Attributes 


DEPTH=area-depth | '*' 
This attribute is required for display panels but 
is not allowed for print panels. The depth of 
the area in lines, including separators if any 
are specified. If '*' is specified, the space 
remaining on the display after all other panel 
elements are allocated is given to this area. 
Only one area in the panel may have '*' 
coded. 


LISTDEF=/ist-name 
The name of the UIM list from which the data 
for this list area is taken. The list must be 
defined in the panel group using the LISTDEF 
tag. 


LIST Tag 


Optional Attributes 


BOTSEP=SPACE | NONE | RULE 
Defines the bottom separator for the list area. 
If SPACE is specified, a line of spaces is 
used. 


NONE indicates that no separator line exists. 


If RULE is specified, a line of underscored 
spaces is used as a separator line. 


SCROLL=YES | NO 
Indicates whether or not the list area is 
scrollable. This attribute is allowed only for 
display panels. YES indicates that the list 
area is intended to be scrollable. For 
SCROLL=YES, a line of spaces is used by the 
UIM to provide a line for the scroll information. 


NO indicates that the list is not scrollable. 
Ordinarily, NO would not be used, but for 
short lists it can be specified to disable the 
scrolling keys for the list area. 


If BOTSEP=SPACE is specified and there are 
no bottom instructions for both the separator 
and scroll information line, one line is used. 


MAXHEAD= 0|1| 2/3] 4 
The maximum number of lines for column 
headings. From 0 to 4 lines can be specified. 
The default is 0, indicating that no column 
headings are allowed. For more information 
on column headings, see “LISTCOL (List 
Column)” on page A-96. This attribute 
includes any heading line required by the 
column group headings. 


When column headings are used, provide 
expansion space for national language trans- 
lation by specifying a MAXHEAD value larger 
than the number of heading lines required. If 
this expansion space is not provided, it must 
be provided within the column width deter- 
mined by the MAXWIDTH attribute of each list 
column (LISTCOL) tag. 


This attribute cannot be specified if the 
HEADSIZE attribute on this tag is specified for 
use with variable column headings. 


BODYSEP=SPACE | INDENT | BOTH | NONE 
The type of visual separation distinguishing 
the body of the area from other elements in 
the area, particularly any top and bottom 
instruction lines within the area. 
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LIST Tag 


SPACE leaves a blank line after the top 
instruction lines and before the bottom instruc- 
tion lines. List columns in the body of the 
area begin in the leftmost position of the 
layout column and are not indented with 
respect to instruction lines. If the area con- 
tains no top or bottom instruction lines, no 
blank lines are reserved before or after the 
area body. 


INDENT is used to indent list columns in the 
body of the area by two positions from the 
leftmost position in the layout column where 
the instruction lines begin. If the area con- 
tains top or bottom instruction lines, no blank 
line is reserved between the instructions and 
the area body except if the area is scrollable. 
If the area is scrollable, a blank line is 
reserved for the scroll information. 


BOTH leaves a blank line after the top instruc- 
tion lines and before the bottom instruction 
lines, and indents the body two positions from 
the leftmost position in the layout column 
where the instruction lines begin. If the area 
contains no top or bottom instruction lines, no 
blank lines are reserved before or after the 
area body. 


NONE does not leave a blank line between 
instruction lines and the body and does not 
indent the body with respect to the layout 
column except if the area is scrollable. If the 
area is scrollable, a blank line is reserved to 
provide a line for the scroll information. 


VIEW=dlalog-variable-name 


This is a BIN 15 dialog variable which deter- 
mines the view of the list which appears to the 
user. Valid values are 0 through one less 
than the number of views defined. The UIM 
changes this variable to match the number of 
the view that is active (where 0 is the first 
view) when the value is not valid or when the 
CHGVIEW dialog command is run for the list 
area. 


The first list view (LISTVIEW) tag for the list 
area defines view 0, the second LISTVIEW 
tag for the list area defines view 1, and so on 
for each LISTVIEW tag in the list area. 


For more information on list views, see 
“LISTVIEW (List View)” on page A-105. The 
VIEW attribute must be specified if more than 
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one LISTVIEW tag is specified for the list 
area. 


ACTOR=NONE | UIM | CALLER. 


If ACTOR=NONE is used, the list is not an 
action list. This attribute is allowed only for 
display panels. No list action (LISTACT) tags 
can be specified and the UIM does not do 
action list processing for the list area. 


If ACTOR=UIM is specified, the actions indicated 
by the LISTACT tags are performed by the 
UIM and must have the ENTER attribute speci- 
fied. 


If ACTOR=CALLER, the actions indicated by the 
LISTACT tags must be performed by the 
calling program of the display panel 
(QUIDSPP) API. 


EXTACT=NO | YES 


Specifies whether or not an action list has 
extended action capability. This attribute is 
allowed only for display panels. With an 
extended action list, the first line below the 
column headings is used for an extended 
action entry. This line contains the action 
option column, along with input-capable fields 
for additional list columns. 


The user can enter a list action option in the 
option field for the extended action entry, 
along with data in the other columns. The 
action identified by the list action tag is per- 
formed using the data entered for the other list 
columns. The data entered into the extended 
action entry columns does not have to match 
the data in an existing list entry. 


EXTACT=NO indicates that the list does not 
have extended action capability. 


EXTACT=YES indicates that the list does have 
extended action capability. This is allowed 
only if ACTOR=UIM or ACTOR=CALLER is speci- 
fied on this tag. The action list option column 
and at least one other list column defined in 
each list view must be defined for extended 
action use with EXTACT=YES on the LISTCOL 
tag. Any LISTACT tags which can operate on 
the extended action field must have 
ACTFOR=BOTH or ACTFOR=EXTACTE specified. 


When a panel is displayed which has an 
extended action list but the list is not currently 
active in the open application, the list is acti- 
vated by the QUIDSPP API. 


SELECT=NONE | SINGLE | MULTI 


If SELECT=NONE is used, the list is not a 
selection list. This attribute is allowed only for 
display panels. 


If SELECT=SINGLE is specified, the list area is 
a single-choice selection list. When a single- 
choice selection list is displayed, a period (.) 
precedes each list entry. The user can select 
only one list entry by typing the slash (/) or the 
country-designated character over the period. 


If SELECT=MULTI is specified, the list is a 
multiple-choice selection list. Multiple list 
entries may be chosen by entering the slash 
(/) or the country-designated character into the 
entry field preceding each list entry to select. 
To deselect a choice, the user should type a 
blank over, or delete the slash or country- 
designated character, in the list entry. 


A value of 1000 is set in the action variable 
for the selected list entries. 


ACTOR=NONE must be specified or made a 
default on this tag if the value of SELECT is 
either SINGLE or MULTI. An action variable 
must be declared for each view of the list. 


MAXACTL= 2|1| 3 


The maximum number of lines used for list 
action descriptions. From 1 to 3 lines can be 
specified; 2 is the default. Only as many list 
action lines as needed are used. This attri- 
bute is allowed only for display panels. 


The only time that MAXACTL=1 would be useful 
is when there are two or more list actions and 
you do not want two lines of list actions after 

national language translation. 


When the UIM formats the first two list action 
lines, it attempts to align the start of each 
action with the line above or below it. This is 
done by moving text a few columns to the 
right on either the first or second line. When 
the text for the third list action line is for- 
matted, the text for the first two lines is not 
moved, but the UIM tries to align the text on 
the third line with the text on the second line. 


PARMS=dialog-variable-name 


This attribute must name a CHAR 255 dialog 
variable, used by the UIM to store parameter 
information for action list processing. This 
attribute is allowed only for display panels and 
is only valid when the ACTOR attribute on this 
tag has a value other than NONE. It must be 


LIST Tag 


used when the list area operates in conjunc- 
tion with a command line on the same panel. 
This provides a way for the user to specify 

parameters that affect action list processing. 


The UIM stores the contents of the command 
line in this variable when the command line 
contains parameters for action list processing. 
The UIM sets the variable to blanks before 
action list processing when the command line 
does not contain parameter information. 


This dialog variable is intended for use in the 
action string for a CMD dialog command spec- 
ified on the ENTER, EXTENTER, PROMPT, or 
EXTPROMPT attribute on the LISTACT tag. 


Note: This variable only contains command 
line contents when the command line is inter- 
preted as specifying parameters for action list 
processing. It does not provide generalized 
access to the contents of the command line. 


HEADSIZE=dialog-variable-name 


This dialog variable specifies the number of 
dialog variables specified on the COLHEAD attri- 
bute of the LISTCOL tag that should be used 
for the list column headings. This attribute is 
not allowed if MAXHEAD is specified. 


This dialog variable can only contain the 
values 0 through 10, as these are the valid 
number of lines for heading text. If this dialog 
variable is not a valid value from 0 through 10, 
the maximum of 10 is used. When using the 
dialog variables from the list specified on the 
COLHEAD attribute of the LISTCOL tag, the vari- 
ables are used in the order defined on the 
COLHEAD attribute. This dialog variable must 
be defined with a BASETYPE of 'BIN 15' on the 
class definition (CLASS) tag. 


The dialog variables on the HEADSIZE attribute 
and the COLHEAD attribute of the LISTCOL tag 
are evaluated like normal dialog variables. It 
is recommend that you set the HEADSIZE 
dialog variable before calling the QUIDSPP 
API and not change it when changing from 
one view to another. It is up to the application 
programmer to not let the list and headings 
shift up and down on panels. 


This attribute may not be specified if the list 
area contains list column groups. 


Optional Text 
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LIST Tag 


area-title 
The title of the area. If no text is specified, no 
title line is allocated to the area. The text 
must appear on the same or next line as the 
tag, can only contain the reverse text (RT) 
tag, and cannot exceed a maximum length of 
55 characters. 


Print Formatting Considerations 


Printed list areas are formatted like those dis- 
played with the following changes:. 


e Printing always starts with the first entry in the 
list. 


e For lists which are incomplete at the top, the 
UIM starts printing with the first entry in the list 
and does not require the list to be marked 
complete at the top. 


e For lists which are incomplete at the bottom, 
the UIM formats and prints until it runs out of 
list entries, then calls the exit program for pro- 
cessing the incomplete list for more entries. 

In general, the exit program is asked for a 

large number of list entries, and if the list is 
not marked complete at the bottom, the exit 
program is called again for more list entries. 


e For layouts greater than one, the UIM formats 
as many entries as can be printed on one 
page, then prints that page. If there are not 
enough entries to fill up a page, the entries 
are balanced across the layout columns. 
There is always a minimum of two entries in 
the first column before putting entries into sub- 
sequent columns. This helps the user under- 
stand how to read the list. For example, a list 
with LAYOUT=2 and only two list entries would 
print as follows: 


Column 1 Column 2 
XXXXXXXX 
XXXXXXXX 


For list panels, there must be room for a 
minimum of two lines of list entries on a page 
besides the column headings. If two lines of 
list entries do not fit on a page, a page eject 
occurs and the list entries are printed on the 
next page. The following example would need 
to fit on one page, or a new page would be 
used. 
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Column 1 Column 2 
XXXXXXXX XXXXXXXXXX 
XXXXXXXX XXXXXXXXXX 


List column headings and group headings are 
repeated on each page if the list area is con- 
tinued onto another page. 


Example 1: List Area 


This example shows an action where the UIM per- 
forms the action requested by the user. 


UIM Source 


:listdef name=outflist 
vars='opt fil nbr usr pri pg sts co'. 
:panel topsep=space 


.Output Files 
:list depth='*' 
listdef=outflist 
maxhead=2 
actor=uim 
parms=pvar. 
:topinst.Type options, press Enter. 
:listact 
enter='CMD CHGSPLFA FILE(&FIL.) ' 
enter='JOB(&USR./&SPID.) SPLNBR(&NBR.) &PVAR. | 
help=opt2 
option=2.2=Change 
:listact 
enter='CMD CNLSPLF FILE(&FIL.)' 
enter='JOB(&USR./&SPID.) SPLNBR(&NBR. ) ' 
help=opt4 
option=4.4=Cancel 
:listact 
enter='CMD DSPSPLF FILE(&FIL.)' 
enter='JOB(&USR./&SPID.) SPLNBR(&NBR. ) ' 
help=opt5 
option=5.5=Display 
:listact 
enter='CMD HLDSPLF FILE(&FIL.)' 
enter='JOB(&USR./&SPID.) SPLNBR(&NBR. ) ' 
help=opt7 
option=7.7=Hold 
:listact 
enter='CMD RLSSPLF FILE(&FIL.)' 
enter='JOB(&USR./&SPID.) SPLNBR(&NBR. ) ' 
help=opt8 
option=8.8=Release 
:listcol var=opt 
usage=inout 
maxwidth=6 
help=hopt.Opt 
:listcol var=fil 


usage=out 
maxwidth=10 
help=hfil.File 
:listcol var=nbr 
usage=out 
maxwidth=6 
help=hnbr.Nbr 
:listcol var=usr 
usage=out 
maxwidth=10 
help=huser.User 
:listcol var=pri 
usage=out 
maxwidth=6 
help=hpri.Pty 
:listcol var=pg 
usage=out 
maxwidth=8 
help=hpg.Pages 
:listcol var=sts 
usage=out 
maxwidth=10 
help=hsts.Status 
:listcol var=co 
usage=out 
maxwidth=10 
help=hco.Copies 
:listview layout=1 


cols='opt fil nbr usr pri pg sts co’. 


:elist. 
:cmdline size=short.Parameters or command: 
:epanel. 


Results 


[ i 
Output Files 


Type options, press Enter. 
2=Change 4=Cancel 5=Display 7=Hold 8=Release 


OPT FILE NBR USER PTY PAGES STATUS COPIES 
_ ffffffffff =onnnn  uuuuuuuuuu p nnn XXXX nnn 
= ffffffffff =onnnn  uuuuuuuuuU p nnn XXXX nnnn 
= ffffffffff |=onnnn  uuuuuuuuuU p nnn XXXX nnn 
= ffffffffff =onnnn  uuuuuuuuuU p nnn XXXX nnn 
* ffffffffff =onnnn  uuuuuuuuuu p nnn XXXX nnn 
_ ffffffffff |onnnn uuuuuuuuuU p nnn XXXX nnn 
= ffffffffff |=onnnn  uuuuuuuuuu p nnn XXXX nnn 
7, ffffffffff |=onnnn  uuuuuuuuuU p nnn XXXX nnn 
2 ffffffffff =onnnn  uuuuuuuuuu p nnn XXXX nnn 
= ffffffffff =onnnn  uuuuuuuuuu p nnn XXXX nnn 
- ffffffffff |=onnnn  uuuuuuuuuu p nnn XXXX nnn 
7 ffffffffff =onnnn  uuuuuuuuuU p nnn XXXX nnn 
ffffffffff |=onnnn  uuuuuuuuuU p nnnn XXXX nnnn 


More... 
Parameters or command: 
===> 


F3=Exit F12=Cancel 


L w, 


Example 2: List Area with Three 
Layout Columns 


This example shows a list area where three 
entries appear in each row of the display. 


LIST Tag 


UIM Source 


:listdef name=dist 
vars='name node'. 
:panel panel-attributes.Distribution 
:list listdef=dist 
depth=8 
maxhead=1. 
:listcol var=name 
usage=inout 
maxwidth=10 
hel p=hxxyyl.Name 
:listcol var=node 
usage=inout 
maxwidth=10 
hel p=hxxyy2.Node 
:listview layout=3 
cols='name node'. 


:elist. 
:epanel. 
Results 
— 
Distribution ] 
Name Node Name Node Name Node 


More... 


F3=Exit F12=Cancel 


L 5 


Example 3: List Area with List 
Column Groups 


This example shows how list columns can be 
grouped together. 


UIM Source 


:listdef name=auth 

vars='user oper mgmt exist' 

vars='read add update delete’. 
:panel panel—attributes.User Authorizations 
:list listdef=auth 

depth='*' 

maxhead=3. 
:listcol var=user 

usage=out 

maxwidth=10 

help=huser 
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LIST Tag 


.User Name 

:listgrp col=objrights 
help=hobjaut.Object Rights 

:listcol var=oper 
usage=out 
maxwidth=7 
.Oper 

:listcol var=mgmt 
usage=out 
maxwidth=7 
«Mgmt 

:listcol var=exist 
usage=out maxwidth=7 
Exist 

:elistgrp. 

:listgrp col=dtarights 
help=hdtaaut.Data Rights 

:listcol var=read 
usage=out 
maxwidth=7 
.Read 

:listcol var=add 
usage=out 
maxwidth=7 
. Add 

:listcol var=update 
usage=out 
maxwidth=7 
.Upd 

:listcol var=delete 
usage=out 
maxwidth=7 
.DIt 

:elistgrp. 

:listview layout=1 


cols='user objrights dtarights 


:elist. 
:epanel. 


Results 


A-88 Application Display Programming V4R1 


User Authorizations 
System: — XXXXXXXX 

-----' Object Rights----- --------Data Rights--------- 

mt Exist Read A 


=) 


So 
® 
i 
DS >< >< >< D6 DK 6 DK DS DE -OK DC OK OK OC OK OS 


User Name 
XXXXXXXXXX 


+ 


XXXXXXXXXX 
XXXXXXXXXX 
XXXXXXXXXX_ 
XXXXXXXXXX. 
XXXXXXXXXX. 
XXXXXXXXXX_ 
XXXXXXXXXX. 
XXXXXXXXXX 
XXXXXXXXXX. 
XXXXXXXXXX. 
XXXXXXXXXX. 
XXXXXXXXXX. 
XXXXXXXXXX. 
XXXXXXXXXX. 
XXXXXXXXXX 
XXXXXXXXXX. 


DS D6 >< D6 >6 DK OE DK DE-DE OK DK OK OK OK OK OKT 
= 
DS De D6 DE DK DK DE-DE DE OE OK DK DE OK OK KE 
DS D6 DE DE DE DE DE DE DE DE DE DE DE DE DE DC KE 
c 
Dg De >< De DK DK DE DE DE DE OK DE OK OK OS KOK TT 
a 


More... 
F3=Exit F12=Cancel 


Example 4: Dynamic List 
Column Heading Formatting 


This example shows how the column headings are 
contained in dialog variables. 


UIM Source 


:listdef name=xmp4 

vars='varl var2 var3'. 
:panel panel-attributes. 
Example of Dynamic Column Headings 
:list listdef=xmp4 

depth='«' 

headsize=colhsize. 
:listcol var=varl 

usage=inout 

maxwidth=10 

colhead='A BCODE F'. 
:listcol var=var2 

usage=inout 

maxwidth=14 

colhead='G H'. 
:listcol var=var3 

usage=inout 

maxwidth=10 

colhead='I J K L'. 
:listview layout=1 

cols='varl var2 var3'. 
:elist. 
:epanel. 


Note: In this example, ABCDEFGHIJK 
and L are dialog variables that would each be set 
to one line of column heading text. In the screen 
that follows, the actual text appears instead of the 
dialog variable names. COLHSIZE is also a 
dialog variable, and in this example it is set equal 
to 4. 


Results 
— 
Example of Dynamic Column Headings 
A I 
B J 
Cc G K 
D H L 
F3=Exit F12=Cancel 


—————————— ee 


LIST Tag 
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LISTACT Tag 


LISTACT (List Action) 


p>—:LISTACT—HELP=he lp-module-name—OPTION=number L > 
BOTH | 
ACTFOR= HLISTE 
EXTACTE 
> > 
LcONFIRM=panel-name— LeNTER='action-text '— LEXTENTER='action-text '— 
> > 
LproMPT='action-text 2 LEXTPROMPT='action-text'— | iseuER | 
NOCMD=——PROMPT: 
> > 
| ENTER | | USREXIT='CALL program-reference = 
NOEXT= L-PRONPT 
MSG 
> > 
LEXTSGID=message- center Lextuse F='qualified-message-file-name = 
> > 
Le6nn=condi¢ion-nane= LavatL=condition-name—! LAVLMSGID=message-identifier— 
> < >< 
Ay NeGretanatafed meesage Fi ieciamel | Laeerencdeseniperon 
The list action (LISTACT) tag defines an operation There is no way to have the UIM perform some 
which takes place on individual items of a list. actions and the calling program perform others. 
This tag is allowed only for display panels. 
Options entered by a user are not actually run When the CMD dialog command is used as the 
until an Enter or Prompt function key is pressed, action performed for the extended action entry in 
allowing the user to select several list items while an action list, the command text should be a 
using the Page Up or Page Down keys. Control Language command, not a System/36 
Environment OCL command. The value *N is 
If ACTOR=UIM is specified on the list area (LIST) substituted in the command text for any dialog 
tag, all actions indicated by LISTACT tags are per- variable from the extended action entry that has a 
formed by the UIM. These actions must have the blank value. An exception to this is when 
ENTER attribute specified, and may also have the NOEXT=MSG is specified on this tag, indicating that 
PROMPT and USREXIT attributes specified. If the command should not be submitted when any 
ACTOR=CALLER is specified on the LIST tag, the of the values for the extended action entry are 
actions are handled by the program which called blank. This consideration applies to the following 
the Display Panel (QUIDSPP) API. In this case, attributes of this tag: 
none of the following attributes can be specified ° ENTER 
on the LISTACT tag: PROMPT 
¢ CONFIRM e EXTENTER 
e ENTER e¢ EXTPROMPT 
e¢ PROMPT 
ie Required Attributes 
e EXTENTER 
e EXTPROMPT HELP=help-module-name 
¢ NOEXT Identifies the associated help module for this 
e EXTMSGID list action. The online help information for all 
e EXTMSGF actively-conditioned list actions is always 


added to the online help information for the 
action column. 
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OPTION=number 


The value associated with the option selected 
for this item in the list. The value must be an 
integer value in the range of 1 through 999. 
The action field variable must be defined with 
a BASETYPE of ACTION on the class definition 
(CLASS) tag. The values of the action field 
are automatically limited to the valid options 
by the UIM. An error occurs when the user 
enters a number in the action field for which 
there is no active LISTACT tag. 


LISTACT Tag 


ified on this tag, NOEXT=MSG must also be 
specified on this tag. 


A maximum of 20 different LISTACT tags for a 
single action list may specify the CONFIRM attri- 
bute. This does not impose any restriction on 
the number of list entries that any one of the 
actions may be applied to. 


For more information on required and recom- 
mended conventions for this attribute, see 
“Confirmation Panel Requirements” on 

page A-94 and “Confirmation Panel 
Conventions” on page A-94. 


Optional Attributes 


ACTFOR=BOTH | LISTE | EXTACTE ENTERS acvoniext 


Specifies the action occurring when the list 


Indicates whether the list action defined is 
allowed for the existing list entries, the 
extended action entry, or both. The default is 
BOTH. 


If LISTE is specified, the action defined is 
valid only in the action fields associated with 
the existing list entries on the display. 


EXTACTE indicates that the action defined is 
valid only in the action field for the extended 
action entry. For example, ACTFOR=EXTACTE 
might be used for Option 1=Create, because 
the create option is not allowed for an existing 
entry. 


CONFIRM=panel-name 


The confirmation panel displayed before the 
list action is performed. The confirmation 
panel must give the user the option to confirm 
or not confirm the list action. If the action is 
confirmed, the appropriate actions from the 
ENTER, EXTENTER, and USREXIT attributes of 
this tag are performed. If the action is not 
confirmed, none of those actions are per- 
formed. 


The actions coded on the PROMPT and 
EXTPROMPT attributes of this tag are not con- 
firmed. The prompt screen that results from 
the PROMPT and EXTPROMPT actions serves as 
the confirmation panel, allowing users to 
change their minds and cancel the action. 
The confirmation panel must be another panel 
defined within this panel group. 


The CONFIRM attribute is only allowed when 
ACTOR=UIM is specified in the LIST tag. 


When the CONFIRM attribute is specified, 
EXTACT=YES is specified on the LIST tag and 
if ACTFOR=BOTH or ACTFOR=EXTACTE is spec- 


action is requested through the ENTER dialog 
command. This attribute is required if 
ACTOR=UIM is specified on the LIST tag. The 
valid forms of action-text are: 


¢ ‘CALL program-reference' 
For a description of the interface between 
the UIM and the exit program for an action 
list option, see the System API Reference. 


¢ ‘CMD commano-string' 
Any dialog variable name in the command 
string must be preceded by an ampersand 
and should be ended with a period to 
denote variable substitution. 


For a description of each of these actions, see 
Appendix B, “UIM Dialog Commands” on 
page B-1. 


This attribute is repeatable, allowing the con- 
struction of long command strings. 


The PARMS attribute on the LIST tag identifies 
a dialog variable that can be substituted into a 
command string on the CMD dialog command. 
Additional functions are provided for list 
actions which use the CMD dialog command. 
When parameters from the command line are 
substituted into a command string, the param- 
eters from the command line override the 
same parameter defined in the command 
string if the parameter in the command string 
is preceded by the "?<" or "??" selective 
prompting characters. 


This function allows a prompt for a command 
to show the parameter values from the 
command line, or to show the current param- 
eter values for the object when an overriding 
parameter is not on the command line. When 
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LISTACT Tag 


the "?<" or "??" selective prompting characters 
are used, it is your responsibility to have the 
current parameter values substituted into the 
command string. 


EXTENTER2=' action-text' 


Specifies the action occurring when the list 
action for the extended action field is 
requested through the ENTER dialog 
command. This attribute is not allowed when 
ACTFOR=LISTE is specified on the LISTACT 
tag, or when EXTACT=NO is specified on the 
LIST tag. 


The syntax and usage of this attribute is the 
same as the ENTER attribute for this tag. If the 
EXTENTER attribute is not specified, the action 
specified on the ENTER attribute is used. 


PROMPT=' action-text' 


Specifies the action occurring when the list 
action is requested through the PROMPT 
dialog command. The valid forms of action 
text are: 


¢ ‘CALL program-reference' 
For a description of the interface between 
the UIM and the exit program for an action 
list option, see the System API Reference. 


¢ ‘CMD commano-string' 
Any dialog variable name in the command 
string must be preceded by an ampersand 
to denote variable substitution. 


For a description of these actions, see 
Appendix B, “UIM Dialog Commands” on 
page B-1. 


This attribute is repeatable, allowing the con- 
struction of long command strings. 


The PARMS attribute on the LIST tag identifies 
a dialog variable that can be substituted into a 
command string on the CMD dialog command. 
Additional command submission support is 
activated for list actions which use the CMD 
dialog command. When parameters from the 
command line are substituted into a command 
string, the parameters from the command line 
override the same parameter defined in the 
command string if the parameter in the 
command string is preceded by the "?<" or 
"22" selective prompting characters. 


This function allows a prompt for a command 
to show the parameter values from the 
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command line, or to show the current param- 
eter values for the object when an overriding 
parameter is not on the command line. When 
the "?<" or "??" selective prompting characters 
are used, it is your responsibility to have the 
current parameter values substituted into the 
command string. 


EXTPROMPT=' action-text' 


Specifies the action occurring when the list 
action for the extended action field is 
requested through the PROMPT dialog 
command. The EXTPROMPT attribute is not 
allowed when ACTFOR=LISTE is specified on 
the LISTACT tag, when EXTACT=NO is speci- 
fied on the LIST tag, or when the PROMPT attri- 
bute is not specified on this tag. 


The syntax and use of this attribute is the 
same as for the PROMPT attribute on this tag. If 
the EXTPROMPT attribute is not specified, the 
action specified on the PROMPT attribute is 
used. 


NOCMD=ENTER | PROMPT 


Specifies the action the UIM performs for the 
ENTER dialog command when the command 
line is blank. 


ENTER indicates that the action on the ENTER 
attribute of this tag should be performed. 


PROMPT indicates that the action on the 
PROMPT attribute of this tag should be per- 
formed. 


This allows you to have a command prompted 
when the command line is empty, but not 
prompted if the command line contains param- 
eters. 


For an explanation of how this attribute inter- 
acts with the NOEXT attribute of this tag, see 
Table A-10 on page A-93. 


NOEXT=ENTER | PROMPT | MSG 


Specifies the action the UIM should perform 
for the ENTER dialog command when one or 
more of the input fields on the extended action 
entry are blank. 


ENTER indicates that the action on the 
EXTENTER attribute of this tag should be per- 
formed. 


PROMPT indicates that the action on the 
EXTPROMPT attribute of this tag should be per- 
formed. 


LISTACT Tag 


MSG indicates that no action should be per- EXTMSGID=' message-identifier' 

formed and that the message specified on the The message identifier of the message dis- 
EXTMSGID attribute of this tag should be sent to played when the action defined by this tag 
the user. When MSG is specified, the cannot be performed because one or more 
EXTMSGID attribute is required. input fields on the extended action entry are 


blank. This attribute is required when 
NOEXT=MSG is specified on this tag; it is not 
allowed otherwise. 


For an explanation of how this attribute inter- 
acts with the NOCMD attribute, see Table A-10. 
This table shows how the NOCMD and NOEXT 


attributes operate when the command line is EXTMSGF=' qualified-message-file-name' 
blank and one or more of the input fields on The message file name that contains the 
the extended action entry are blank. message identifier. The attribute is allowed 


only when the EXTMSGID attribute is specified 


Table cee Ney ane MOL ARH El on this tag. If the DFTMSGF attribute is not 


eeen specified on the panel group (PNLGRP) tag, 
NOCMD NOEXT Result this attribute must be specified when the 
ENTER ENTER EXTENTER attribute is EXTMSGID attribute on this tag is specified. 
meee COND=condition-name 
PROMPT ENTER EXTPROMPT attribute is The list action is in effect on the panel only if 
used the condition specified is true. The condition 
ENTER PROMPT _ EXTPROMPT attribute is must be defined in the panel group prolog with 
used the condition definition (COND) tag. If the 
PROMPT PROMPT EXTPROMPT attribute is conditions for all LISTACT tags are false, the 
used action column still appears on the display, but 
ENTER MSG EXTMSGID message is no option numbers are valid. It is up to you to 
displayed ae that some options remain valid for the 
PROMPT MSG EXTMSGID message is 
displayed AVAIL=condition-name 
The list action is available only if the condition 
This table is used only when all of the fol- specified evaluates to true. The condition 
lowing are true: must be defined in the panel group prolog with 


the COND tag. 
1. A list action option is being processed for 


the extended action entry. 

2. The command line is blank. 

3. One or more of the input fields on the 
extended action entry are blank. 


Unavailable actions are displayed with an 
asterisk (*) overlaying the first part of the 
action description. Online help information is 
displayed for unavailable list actions. 


When the condition is true, the list action is 
available. When the condition is false, the list 
action is not available. Any condition speci- 
fied on the COND attribute takes precedence 
over this attribute. 


USREXIT=' CALL program-reference' 
Specifies the list exit program the UIM calls to 
update or delete this list entry after the action 
defined in either the ENTER, EXTENTER, PROMPT, 
or EXTPROMPT attribute of this tag is performed. 


The program is passed information that AVLMSGID=message-identifier 
includes an indication of whether the option The message identifier of the message dis- 
succeeded or failed. played when a number is entered and is not 


available as specified by the AVAIL attribute of 
this tag. This attribute is allowed only when 
the AVAIL attribute is specified. 


If this attribute is not specified, the UIM dis- 
plays a default message stating that the 
option number is not currently available. 


For a description of the CALL dialog 
command, see Appendix B, “UIM Dialog 
Commands’ on page B-1. 


For a description of the interface between the 
UIM and the program for an action list, see 
the System API Reference. 
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AVLMSGF= ' qualified-message-file-name' 


The message file name that contains the 
message identifier. The attribute is allowed 
only when the AVLMSGID attribute of this tag is 
specified. If the DFTMSGF attribute is not speci- 
fied on the PNLGRP tag, this attribute must 
be specified when the AVLMSGID attribute on 
this tag is specified. 


Optional Text 


action-description 


The text shown as part of the top instructions 
for the list area. If no text is supplied, none is 
listed in the instruction part of the list area for 
this action. The text must appear on the 
same or next line as the tag and can only 
contain the reverse text (RT) tag. 


The instruction line is formed by concatenating 
the text from the various list actions, sepa- 
rated by three spaces. If the text does not fit 
on the rest of a line, it is placed on the next 
line. 


Confirmation Panel Requirements 


The panel named on the CONFIRM attribute of this 
tag must follow these conventions: 


The ENTER attribute on the display panel 
(PANEL) tag of the confirmation panel must 
have 'RETURN 100' coded. This indicates to 
the UIM that the action is confirmed by the 
user. 


No ACTION attribute on a key list item (KEY) 
tag can be assigned to the RETURN dialog 
command, because the UIM is handling the 
display of the panel and is not able to interpret 
the returned value. 


The confirmation panel must have a list area. 


The list used as the confirmation list must not 
be the same list displayed in the action list 
panel. 


The confirmation panel must not have a menu 
bar, action list, command line, or menu area. 
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Confirmation Panel Conventions 


The panel named in the CONFIRM attribute of this 
tag should follow these conventions: 


It should have title text and top instructions to 
describe the panel. 


It should have a single list area with a list defi- 
nition containing the same (or a subset of) the 
columns defined in the original action list. 


The list should be scrollable. 


If the action list has multiple views, the confir- 
mation list should also have multiple views 
and the same dialog variable should be used 
for the view variable on both lists. The confir- 
mation panel should have a function key 
defined for the CHGVIEW dialog command. 
When the same view variable is used for both 
lists, it allows a change view operation on the 
confirmation panel to change the view of the 
action list panel when it is redisplayed. 


It should have function key definitions for the 
ENTER, CANCEL, PAGEDOWN, PAGEUP, 
HELP, and PRINT dialog commands. 


If a general exit program is defined, it should 
avoid making changes to the action list and 
avoid changing condition values that affect the 
redisplay of the original action list panel. 


The list used on the confirmation panel should 
not be used on anything but a confirmation 
panel, because the UIM deletes and changes 
the contents of that list. If multiple confirma- 
tion panels are used within a UIM application, 
they use the same list definition. 


Most of the help information for the action list 
panel can be used for the confirmation panel, 
but separate help information should be pro- 
vided for the action column and the extended 
help. 


The class definition for the list option variable 
defined with a BASETYPE of ACTION on the 
CLASS tag should have a WIDTH attribute on 
the CLASS tag to accommodate the largest 
list action option on the action list panel. For 
example, if the largest option number on the 
action list panel is 12, WIDTH=2 should be 
specified on the class definition for the action 
variable. This ensures that the option number 
is displayed in the same position under the 


column heading on the confirmation panel as 
it was on the action list panel. 


¢ Only the values for the input capable fields of 
the extended list action entry will be displayed 
on the confirmation panel. All other columns 


UIM Source 


:listact option=2 
help='option/2' 
enter='CALL CHGPGM' 
.2=Change 

:listact option=4 
help='option/4' 
enter='CALL DLTPGM' 
confirm=CONFDLT 
-4=Delete 

:listact option=5 
help='option/5' 
enter='CALL DSPPGM' 
.5=Display 


LISTACT Tag 


will be shown as blanks even though there 


may be a value there. 


Example: List Actions 


This example shows how the action options on a 


display are defined. 
Results 


Type choices, press Enter. 
2=Change 4=Delete 5=Display 
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LISTCOL Tag 


LISTCOL (List Column) 


;-—— Syntax for Display Panels 


Pe eto cole VAR aor On) che VOntan eC name AND IE ae, eeu) > 
ty! 
>—USAGE=——OUT > 
Linour el Pehelpsmodutecnone- Coie colimeidentipies 
> > 
LANE? ¢s¢-cotumn=name! L gustiry= LEFT | po | 
RIGHT EXTACT=——YES 
START 
END 
> > 
LprompT=‘action-text LPSPVALUESHidiogsvardabtesnane= 
COLHEAD='dialog-variable-name-list' I Seem 
DISPLAY=——NO 
>< 


eee l iidnsneddine! 


> 
YES 
Pee oe 


;—— Syntax for Print Panels 


pie set SEOs 3 AS bio On ce couch ae tenance MANNII = pao umeNLaEn 
ty! 


> 


usaGe-ouT 


> 


> 


> 
Leggizeotumie iientirion Lgusti FY=——LEFT 
RIGHT: 
START 
END 


LcOLHEAD= ‘dialog-variable-name-list = 


Lay l lmosheudnic= 


>< 


The list column (LISTCOL) tag defines a column 
that may belong to any of several list views. This 
tag is allowed for display panels and print panels. 
It specifies the dialog variable, whether the field 
allows the user to enter data or is for output only, 
the column width, and the column heading. 


Required Attributes 


VARz=list-object-variable-name 
The name of the variable from the underlying 
list object to display in this column. 


MAXWIDTH=column-width | '*' 
The maximum width of the column. The width 
may allow for translation of the column 
heading into other languages. The minimum 
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size for a column heading is four characters. 
Specification of a width longer than that 
defined in the class definition (CLASS) tag 
allows more room for the formatting of column 
headings, but does not allow more data to be 
entered into the field. Specification of a width 
shorter than the class width on the CLASS tag 
is allowed only for CHAR or IGC variables, 
and is not allowed for input columns. 


If is coded, the remainder of the area width 
is used for the column, and values in that 
column can be truncated. Only one column 
may have ™' coded. A warning message is 
put in the compiler listing if the column with "™' 
specified is not the last column of all views. A 
two- to five-character separator is maintained 
between columns. 


USAGE=OUT | INOUT 


The display use of the column. This attribute 
is required for display panels, but is optional 
for print panels. 


USAGE=OUT defines an output data column. 
OUT indicates that the variable displayed is 
for output only and cannot be changed by the 
user. 


USAGE=INOUT defines a data entry column. 
INOUT indicates that the variable is for data 
entry and can be changed by the user. 
USAGE=INOUT fields are not allowed for print 
panels, but are required for the action column 
of an active list. 


LISTCOL Tag 


window near this list column. This attribute is 
allowed only for display panels. 


If the list column is part of a list column group 
defined by the LISTGRP tag and both the 
LISTCOL and LISTGRP tags have the NAME 
attribute specified, the list column name is set 
in the dialog variable specified on the CSRNAME 
attribute of the display panel (PANEL) tag 
when the cursor is anywhere in the list 
column. The list group name is set for the 
CSRNAME attribute on the PANEL tag when the 
cursor is positioned between columns or on 
an unnamed list column within the named list 
group. For a description of the CSRNAME attri- 
bute, see “PANEL (Display Panel)” on 

page A-122. 


Optional Attributes 
JUSTIFY=LEFT | RIGHT | START | END 
HELP=help-module-name 


Identifies online help information which 
explains the purpose of the column in this list. 
This attribute is allowed only for display 
panels. The help module name may be a 
name imported from another panel group, but 
must follow the rules for names outlined 
earlier in this chapter. For more information 
on the rules for names, see “Name Syntax” on 
page A-4. 


The HELP attribute is not allowed if this column 
is part of a list column group defined by the 
list group (LISTGRP) tag, but is required if the 
column is not part of a group. 


COL=column-identifier 


The identifier of the column, which can be 
referred to in the COLS attribute on the list 
view (LISTVIEW) tag. If the identifier is not 
supplied, it defaults to the dialog variable 
name specified on the VAR attribute of this tag. 
These names are in a separate name space 
from all other names and are meaningful only 
within the list area, not to the panel group. 


A list column identifier cannot be specified and 
no default column name is assumed if the 
column is part of a list column group defined 
by the LISTGRP tag. 


NAME=/ist-column-name 


The name associated with the column. For 
more information on the rules for naming, see 
“Name Syntax” on page A-4. 


This name can be used with the Add Pop-Up 
Window (QUIADDPW) API to position a 


Indicates whether the dialog variable values 
should be left-justified or right-justified within 
the list column. If the ALIGN attribute of this 
tag is omitted, the default right-justifies values 
for numeric dialog variables and left-justifies 
nonnumeric dialog variables. 


Leading blanks are preserved when the dialog 
variable is left-justified. Right-justification 
strips all trailing blanks. The UIM rules for 
editing a numeric dialog variable produces a 
displayable value which does not contain any 
leading blanks. 


A common case where you might want to 
override the alignment default is for a column 
of values whose BASETYPE is defined as 
numeric on the CLASS tag, but whose dis- 
playable values are sometimes special values 
generated through a translation list. For more 
information on translation lists, see “TL 
(Translation List)” on page A-159. 


START is a synonym for LEFT and END is a 
synonym for RIGHT. 


EXTACT=NO | YES 


Specifies whether or not this list column is 
input-capable for the extended action entry. 
This attribute is allowed only for display 
panels. 


EXTACT=NO specifies that this list column does 
not have an input-capable field in the 
extended action entry. 


EXTACT=YES specifies that this list column 
does have an input-capable field in the 
extended action entry. When EXTACT=YES is 
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specified on the list area (LIST) tag, 
EXTACT=YES must be specified on at least two 
columns in each list view, including the action 
column. 


Any column with EXTACT=YES specified must 
be in every view of the list area. 


PROMPT=' action-text' 


The action occurring when F4=List is 
requested through the PROMPT dialog 
command. This attribute is allowed only for 
display panels. This attribute is not allowed 
for a dialog variable defined with a BASETYPE 
of ACTION on the CLASS tag or for any 
USAGE=OUT list columns on this tag. The valid 
forms of action text are: 


¢ ‘CALL program-reference' 
For a description of the interface between 
the UIM and the exit program for a cursor- 
sensitive prompt, see the System API Ref- 
erence. 


e ‘RETURN positive-integer' 
For a description of these actions, see 


Appendix B, “UIM Dialog Commands” on 
page B-1. 


DSPVALUE=' dialog-variable-name' 


The dialog variable containing the current data 
entered in the list entry which contains the 
cursor. This attribute is allowed only for 
display panels and when the PROMPT attribute 
is coded on this tag. This variable is updated 
regardless of whether or not the variable pool 
is updated. The variable pool is updated 
based on the VARUPD attribute of the key item 
(KEY1) or pull-down field choice (PDFLDC) 
tag. This updating is independent of the 
normal updating of the variable pool. 


The dialog variable specified must be defined 
on the CLASS tag as a CHAR or IGC variable 
whose length is the same as the width of the 
dialog variable specified on the VAR attribute of 
this tag. No translation processing or validity 
checking is performed for the value before it is 
placed in this variable. Character set and 
code page conversion is performed for this 
variable if the class of the variable named on 
the VAR attribute of this tag specifies that the 
character set and code page conversion 
should be performed. 
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COLHEAD=' dialog-variable-name-list' 


A list of dialog variables separated by blanks, 
specifying the column heading placed above 
the list items in the list area. Up to ten dialog 
variables can be specified. These dialog vari- 
ables must have a BASETYPE of CHAR or IGC 
specified on the CLASS tag, and must have a 
width greater than or equal to the class width 
of the dialog variable specified on the VAR 
attribute of this tag, and less than or equal to 
the width specified on the MAXWIDTH attribute of 
this tag. All variables specified on a single 
COLHEAD attribute must be defined with the 
identical class. 


Each dialog variable is used as a line of 
column heading text. The UIM does no 

aligning or justification on the contents of 
these dialog variables. 


If this attribute is used, column heading text 
cannot be specified after the period for this 
tag, the MAXHEAD attribute must not be speci- 
fied on the LIST tag, but the HEADSIZE attribute 
of the LIST tag must be specified. 


This attribute may not be used on list columns 
that are part of list column groups. 


DISPLAY=YES | NO 


Indicates whether or not the fields in the list 
column are visible when the panel is dis- 
played. This attribute is allowed only for 
display panels. YES indicates that the fields 
in the list column are visible. 


NO indicates that the fields in the list column 
are not visible. NO can only be specified for a 
column in the list when USAGE=INOUT is spec- 
ified on this tag and ACTOR=NONE is specified 
on the LIST tag. 


AUTOSKIP=YES | NO 


Indicates whether or not the cursor should 
automatically move to the next input field 
when data is entered in the last position of the 
list column field. This attribute is allowed only 
for display panels. YES is the default. 


YES indicates that the cursor automatically 
moves to the next input field. 


NO indicates that the cursor does not auto- 
matically move to the next input field. NO can 
only be specified for a column in the list when 
USAGE=INOUT is specified on this tag and 
ACTOR=NONE is specified on the LIST tag. 


Optional Text 


column-heading 
The column heading placed above the column 
in the reserved part of the list area. If no 
column heading or the COLHEAD attribute is 
specified, no column heading is displayed. 


The text may appear on more than one line 
and can only contain the reverse text (RT) 
tag. 


Each word of the column heading is placed on 
a new line. If multiple words are necessary in 
a line of the column heading, they must be 
enclosed in apostrophes ('). Each word or 
quoted string must fit within the maximum 
column width defined by the MAXWIDTH attri- 
bute of this tag. The maximum number of 
words or quoted strings allowed is specified 
by the MAXHEAD attribute on the LIST tag. 
Column headings are not allowed if MAXHEAD=0 
is used for the list area. 


Column headings are justified according to the 
JUSTIFY attribute of this tag only if they are 
specified as text. No justification is done 
when the COLHEAD attribute is specified on this 
tag. 


If no column heading text or COLHEAD attribute 
is specified on any LISTCOL tag for the area, 
no lines are reserved on the display for 
heading information. 


Formatting Considerations 


When the width of the column data is less than 
the width of the column heading text, the column 
data is centered under the column heading text. If 
the data does not center evenly under the 
heading, the additional space is placed on the 


LISTCOL Tag 


right for JUSTIFY=LEFT and on the left for 
JUSTIFY=RIGHT. The following example shows all 
three situations: 


Center Data Align Left Align Right 
XXXXXXX XXXXXXX nnnnnnnn 
XXXXXXX XXXXXXX nnnnnnnn 
XXXXXXX XXXXXXX nnnnnnnn 
XXXXXXX XXXXXXX nnnnnnnn 


When the width of the column data is greater than 
the width of the column heading text, the column 
heading text is adjusted to the left for 
JUSTIFY=LEFT and to the right for 
JUSTIFY=RIGHT. The following example shows 
these situations: 


Align Left Align Right 
XXXXXXXXXXXX nnnnnnnnnnnnn 
XXXXXXXXXXXX nnnnnnnnnnnnn 
XXXXXXXXXXXX nnnnnnnnnnnnn 
XXXXXXXXXXXX nnnnnnnnnnnnn 


If the column heading text requires more than one 
line, the shorter lines of text are centered with 
respect to the longest line. If the shorter lines do 
not center evenly under the longer lines, the addi- 
tional space is on the right for JUSTIFY=LEFT and 
on the left for JUSTIFY=RIGHT. The following 
example shows all situations: 


Line Up Line Up Line Up Line Up 


Line Up Head Head Head Head 
Right Right Right Right Left 
nnnnnnn = nnnnnnn nnn nnnnnnnnn XX 
nnnnnnn = nnnnnnn nnn nnnnnnnnn XX 
nnnnnnn = nnnnnnn nnn nnnnnnnnn XX 
nnnnnnn = nnnnnnn nnn nnnnnnnnn XX 
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LISTDEF Tag 


LISTDEF (List Definition) 


>>—: LISTDEF—NAME=1 ist-name—VARS='dialog-variable-list' > 

> > 
LcHevaR=dialog-variable-name— LsG1D=message- ident veal 

> > 
L_SGIDVAR=dialog-variable-name— Luse F='qualified-message-file-name a 

> > 
LSpRrELAGsdnetogsvardaplesngne=| LempHasis= 'dialog-variable-emphasis-list = 

PROTECT='dialog-variable-usage-list' 


The list definition (LISTDEF) tag defines UIM lists 
which are data structures maintained by the UIM. 
These lists contain the data for list areas pre- 
sented on the display. UIM lists consist of a vari- 
able number of rows. Each row contains one or 
more columns, and each column in the row con- 
tains a copy of one dialog variable value. These 
lists are manipulated by the program using the 
UIM application programming interfaces (APIs). 
Lists may be shared among panels which contain 
list areas. 


Required Attributes 


NAME=list-name 
The name of the list object. This name must 
be unique within the panel group. For more 
information on the rules for naming, see 
“Name Syntax” on page A-4. 


VARS=' dialog-variable-list' 
The list of up to 50 variables which make up 
the columns of the list. All dialog variables in 
this list must be previously defined using the 
variable definition (VAR) tag in this panel 
group. Not all of these variables need to be 
displayed in a view defined with the list view 
(LISTVIEW) tag. The variable names in the 
list are separated by blanks. 


The UIM automatically determines what 
column is used for action list or selection list 
processing by identifying the variable specified 
on the VARS attribute and defined with a 
BASETYPE of ACTION on the class definition 
(CLASS) tag. An action column is required for 
each list view when an ACTOR or SELECT value 
other than NONE is specified, or when 
SELECT=SINGLE or MULTI is specified on the 
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list area (LIST) tag. Only one column of a list 
may be specified as an action column. 


Optional Attributes 


CHGVAR=dialog-variable-name 
Specifies that any list entry values entered by 
the user must be compared to values already 
in the list entry. This attribute also indicates 
where the comparison result should be stored. 
The dialog variable specified must be one of 
the variables listed on the VARS attribute of 
this tag, and must be defined with a BASETYPE 
of CHAR 1 on the CLASS tag. 


List values are compared using the internal 
form of each dialog variable rather than its 
display form. If any values in the list entry are 
changed, the list value associated with the 
dialog variable specified on this attribute is set 
to '1'. If all the new list values are equal to 
the old list values, no special processing is 
performed; the dialog variable specified for 
this attribute is not changed. 


Note: The dialog variable specified on this 
attribute is set to '1' each time the user 
changes the list entry, scrolls the list, or uses 
some other function key. The list value asso- 
ciated with the dialog variable specified on this 
attribute is set to '1' twice if a value in the list 
is changed, the list is scrolled, scrolled back 
again to the original position, and the list entry 
is changed back to its original value. 


An application program can use the list value 
for the dialog variable specified on this attri- 
bute to determine which list entries are 
changed by the user. The application is 
responsible for setting and resetting the list 
entry value to something other than '1'. It 


does this by updating the list entry after the 
input values are processed and before the list 
is redisplayed to make the comparison reli- 
able. 


MSGID=message-identifier 


The message identifier of a message that is 
displayed to the user when the UIM list is 
empty. If no message identifier is specified 
with either the MSGID or MSGIDVAR attribute on 
this tag, no message is displayed when the 
list is empty. The MSGID and the MSGIDVAR 
attributes cannot both be used on the same 
LISTDEF tag. 


MSGIDVAR=dialog-variable-name 


A dialog variable containing the message 
identifier of a message displayed to the user 
when the UIM list is empty. The dialog vari- 
able specified must be defined with a 
BASETYPE of 'CHAR 7' on the CLASS tag. If 
no message identifier is specified with either 
the MSGID or MSGIDVAR attribute on this tag, no 
message is displayed when the list is empty. 
The MSGID and the MSGIDVAR attributes cannot 
both be used on the same LISTDEF tag. 


MSGF=' qualified-message-file-name' 


The message file name containing the 
message identifier specified on the MSGID or 
MSGIDVAR attribute. The attribute is allowed 
only when the MSGID or MSGIDVAR attribute is 
specified on this tag. If the DFTMSGF attribute 
is not specified on the panel group (PNLGRP) 
tag, this attribute must be specified when the 
MSGID or MSGIDVAR attribute on this tag is 
specified. 


PRTFLAG=dialog-variable-name 


Specifies the name of a dialog variable in the 
list definition containing a character printed on 
the first character of each list entry. For each 
list entry printed, the character stored in the 
dialog variable is printed on the first column. 
The dialog variable specified must be one of 
the variables listed on the VARS attribute of this 
tag, and must be defined on the CLASS tag 
with a BASETYPE of CHAR 1 and a width of 1. 
This attribute is intended to be used for output 
listing applications where a special character 
needs to be printed in column one. 


EMPHASIS=' dialog-variable-emphasis-list. ' 


The list of dialog variables containing the 
emphasis or color associated with each of the 
variables listed on the VARS attribute of this 


LISTDEF Tag 


tag. The number of items in the list must be 
the same as the number of dialog variables 
specified on the VARS attribute. Only one 
emphasis is allowed for each variable listed, 
but a particular emphasis value may apply to 
more than one variable. A value of '*' should 
be specified to indicate that normal emphasis 
should be used with the corresponding vari- 
able listed on the VARS attribute, and also used 
for list columns not displayed in any list view. 


The dialog variables specified on this attribute 
cannot be one of the variables listed on the 
VARS attribute of this tag. 


Each variable in the list must be defined with 
a BASETYPE of CHAR 1 on the CLASS tag. 
When an entry is added to the list or an 
existing entry is updated, the values for these 
variables determine the emphasis used when 
that entry is displayed. The following table 
shows the values that can control the 
emphasis. 


Table A-11. Emphasis Values 

Value | Output Field Input 
Field 

0 Normal Normal 

1 Emphasize Emphasize 

2 De-emphasize Normal 


Normal and de-emphasis are the same on a 
monochrome device. 


If a dialog variable listed in this attribute has a 
value specified other than one of the above 
values, normal emphasis is used. If this attri- 
bute is not specified, normal emphasis is 
used. 


This attribute does not control emphasis 
during printing. 


PROTECT=' dialog-variable-usage-list' 


The list of dialog variables containing the 
value used to override the USAGE attribute of 
the list column (LISTCOL) tag for each of the 
variables listed on the VARS attribute of this 
tag. The number of items in the list must be 
the same as the number of dialog variables 
specified on the VARS attribute. Only one pro- 
tection value is allowed for each variable 
listed, but a particular protection value may 
apply to more than one variable. 
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LISTDEF Tag 


A value of '*' should be specified to indicate 
that there is no override for the USAGE attribute 
on the LISTCOL tag for the corresponding 
variable listed on the VARS attribute. A value 
of '*' is also used for list columns not dis- 
played in any list view. 


The dialog variables specified on this attribute 
cannot be one of the variables listed on the 
VARS attribute. 


Each variable in the list must be defined with 
a BASETYPE of CHAR 1 on the CLASS tag. 
When an entry is added to the list or an 
existing entry is updated, the values for these 
variables determine the protection whenever 
that entry is displayed. This attribute over- 
rides the USAGE attribute from the LISTCOL 
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tag. The valid values for the dialog variables 
specified on this attribute are as follows: 


1' The variable use is output-only. 


‘0’ The use is controlled by the USAGE 
attribute on the LISTCOL tag. 


Changing a list option field for an action list or 
selection list to output-only does not affect list 
processing. If the action field contains an 
option number or selection value but is dis- 
played as output-only, the option is processed. 


If a dialog variable listed in this attribute is not 
specified or has a value specified other than 
'1' or '0', the use is controlled by the USAGE 
attribute of the LISTCOL tag. 


LISTGRP Tag 


LISTGRP (List Column Group) 


;—— Syntax for Display Panels 
p>>—:LISTGRP—COL=column-identifier—HELP=help-module-name > 
> > 
Lvame=1 is £261 unmeanoup=nie= ‘* Lgpoussnedding-! 
Ps 
COLSEP=——N 
>—:ELISTGRP. >< 
;—— Syntax for Print Panels 
p>—:LISTGRP—COL=column-identifier L 7 > 
mal group-heading 
COLSEP=——N 
>—:ELISTGRP. >< 


The list column group (LISTGRP) tag groups 
columns in a list area together under a single 
heading that applies to all the columns. This tag 
is allowed for display panels and print panels. 
Columns may be defined within the list area that 
do not belong to any list column group. This tag 
cannot be used in a list area if MAXHEAD=0 is spec- 
ified on the list area (LIST) tag for the area. 


There are some restrictions on the kinds of 
columns that can exist within a column group. 


e The action column of the list cannot be in a 
column group. 


e All or none of the columns can have column 
headings. 


¢ Column groups cannot be nested. 


e At least one column must be defined within a 
column group. 


Required Attributes 


COL=column-identifier. 
The identifier of the column group, which is 
referred to in the COLS attribute on the list view 
(LISTVIEW) tag. These names are in a sepa- 
rate name space from all other names and are 
meaningful only within the list area, not within 
the panel group. 


HELP=help-module-name 
Identifies online help information which 
explains the purpose of the column group in 


this list. This attribute is required for display 
panels; it is not allowed for print panels. The 
help module name may be a name imported 
from another panel group, but must follow the 
rules for names outlined earlier in this chapter. 
For more information on the rules for names, 
see “Name Syntax” on page A-4. 


Optional Attribute 


NAME=list-column-group-name 
The name associated with the group. This 
attribute is allowed only for display panels. 
For more information on the rules for naming, 
see “Name Syntax” on page A-4. This name 
can be used with the Add Pop-Up Windows 
(QUIADDPW) API to position a window near 
this list column group. 


COLSEP=* | N 
The number of spaces by which to separate 
columns in a list column group. COLSEP=* 
causes UIM to calculate the width of the 
column separator. The calculated width is 
between 2 and 5 spaces. COLSEP=N can be 
any positive number. When choosing a value 
for N, keep in mind the widths of the columns. 
This attribute does not affect the space 
between list column groups and other list 
columns. It also does not affect the space fol- 
lowing selection columns in list column 
groups. 
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LISTGRP Tag 


Optional Text 
group-heading 


The group heading text placed above the 
column group in the heading part of the list 
area. This heading must fit on one line over 
the columns in the group. It is centered over 
the group of columns and has a graphic indi- 
cation of the number of columns over which it 
spans. The headings of the columns ina 
column group may span different numbers of 
lines. The group heading appears on the line 
immediately above the tallest column heading 
of the group. 


No column in a column group may have 
MAXWIDTH="' specified on the list column 
(LISTCOL) tag. The columns and the separa- 
tors between the columns define the width 
allocated for the group heading. The group 
heading must be no longer than this width. 


If no column headings are specified on any of 
the columns of the group, the group heading 
appears immediately above the column data. 


The text must appear on the same or next line 
as the tag and can only contain the reverse 
text (RT) tag. 


Example: List Column Group 


This example uses a column separator of 1. 
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UIM Source 


:listdef name=listl 
vars='seq colname more table text'. 
:panel panel-attributes.Select and Sequence Columns 
:list listdef=listl 
depth='*' 
maxhead=3. 
:topinst.Type sequence numbers (1-999) to select 
columns, press Enter. 
:listcol var=seq 
usage=inout 
maxwidth=3 
help=hseq.Seq 
:listgrp col=column 
colsep=1 
help=hlistgrp. 
:listcol var=colname 
usage=out 
maxwidth=18.Column 
:listcol var=more 
usage=out 
maxwidth=1. 
:elistgrp. 
:listcol var=table 
usage=out 
maxwidth=20 
help=htable.Table 
:listcol var=text 
usage=out 
maxwidth=25 
help=htext.Text 
:listview layout=1 
cols='seq column table text’. 
:elist. 
:epanel. 


Results 


[ | 
Select and Sequence Columns 


Type sequence numbers (1-999) to select columns, press Enter. 


Seq Column Table 
___—_EXTRALONGCOLUMNNAM > = TABLE DESCRIPTION 
____—_- SHORTCOLUMNNAME 


ex 
TEXT DESCRIPTION 


TABLE DESCRIPTION TEXT DESCRIPTION 


Bottom 


F3=Exit F4=Prompt  F12=Cancel 


ee 


LISTVIEW Tag 


LISTVIEW (List View) 


p>—: LISTVIEW—COLS='column-identifier-list' 


; j 
: + | 
LAYOUT=——number-of-layout-columns 


>< 


The list view (LISTVIEW) tag defines one of the 
views of a list presented in a list area. This tag is 
allowed for both display panels and print panels. 


Multiple list views can be defined in an area and 
can be changed using the CHGVIEW dialog 
command, which can be assigned to a function 
key or to a pull-down choice. If there is more than 
one list view on the panel and the CHGVIEW 
dialog command is performed, the list area with 
the cursor in it changes views. 


The view may also be established in a program by 
changing the value of the dialog variable specified 
on the VIEW attribute on the list area (LIST) tag. 
Views are numbered consecutively from zero to 
one less than the number of LISTVIEW tags 
defined in this area. The first LISTVIEW tag for 
the list area defines view zero, the second 
LISTVIEW tag defines view one, and so on for 
each LISTVIEW tag in the list area. 


If the ACTOR attribute on the LIST tag has a value 
other than NONE, the action column of the list 
must appear in all views of the list area for the 
panel. If the SELECT attribute on the LIST tag has 
a value other than NONE or MULTI, the action 
column of the list must appear in all views of the 
list area. 


Although multiple views can be defined for a print 
panel, only the view identified by the VIEW attribute 
on the LIST tag is printed when the Print Panel 
(QUIPRTP) API is called. To print more than one 
view, the QUIPRTP API must be called multiple 
times, updating the view dialog variable between 
each call to QUIPRTP. 


Required Attribute 


COLS=' column-identifier-list' 
A list of column or column group identifiers 
which are separated by blanks. This list iden- 
tifies columns and groups that are part of this 
view. 


All variables used in this view must be distinct. 


Optional Attribute 


LAYOUT=1 | number-of-layout-columns 
Indicates whether more than one set of 
columns should be presented on the display 
at one time. If the width of columns defined 
by the COLS attribute of this tag is small, it 
may be possible to position more than one set 
of the columns on the display or page. 


The format used for multiple-column layout 
divides the entire display or page width into 
layout columns of equal size, with a separator 
of at least three characters between layout 
columns. All list columns specified on the 
COLS attribute of this tag must fit within a 
single layout column. 


For all panels with WIDTH=132 on the display 
panel (PANEL) or print panel (PRTPNL) tags, 
a value from 1 through 10 is allowed. For 
panels with WIDTH less than 132, a value from 
1 through 6 is allowed. 


The following tables show the available column 
width and what positions are used for each layout 
column, depending on the value of the LAYOUT 
attribute. The first table applies to all panels with 
WIDTH=80 specified on the PANEL or PRTPNL 
tags. The second table applies to panels with 
WIDTH=132 specified. 
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LISTVIEW Tag 


Table A-12. Layout Values for Width=80. Layout column widths and positions for panels with WIDTH=80. 


Layout Layout Layout 1 Layout 2 Layout 3 Layout 4 Layout 5 Layout 6 

Width Column Column Column Column Column Column 
Positions Positions Positions Positions Positions Positions 

1 78 2-79 

2 37 2-38 43-79 

3 24 2-25 29-52 56-79 

4 17 2-18 22-38 42-58 62-78 

5 13 2-14 18-30 34-46 50-62 66-78 

6 10 2-11 15-24 28-37 41-50 54-63 67-76 


Table A-13. Layout Values for WIDTH=132. 


Layout column widths and positions for panels with WIDTH=132. 


Layout Layout Layout 1 Layout 2 Layout 3 Layout 4 Layout 5 Layout 6 

Width Column Column Column Column Column Column 
Positions Positions Positions Positions Positions Positions 

1 130 2-131 

2 63 2-64 69-131 

3 4 2-42 46-86 90-130 

4 30 2-31 35-64 68-97 101-130 

5 23 2-24 28-50 54-76 80-102 106-128 

6 19 2-20 24-42 46-64 68-86 90-108 112-130 


Table A-14. Layout Values for WIDTH=132. Layout column widths and positions for panels with WIDTH=132. 


Layout Layout Width Layout 7 Layout 8 Layout 9 Layout 10 
Column Column Column Column 
Positions Positions Positions Positions 
7 16 97-112 
13 66-78 82-94 
11 86-96 100-110 114-124 
10 10 80-89 93-102 106-115 119-128 


If a WIDTH of less than 80 or a width between 81 
and 131 is specified on the PANEL tag, the fol- 
lowing algorithm can be used to determine the 


layout width: 


1. Subtract 2 from the width of the panel. 


2. Subtract 3*(layout-1) from the result of step 1. 
This is the total separator space between the 


layouts. 
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3. Divide the result of step 2 by the layout; do 
not round up. This is the layout width. 


4. If the remainder from step 3 is greater than 
(layout-1), the separator between the layouts 
is 4. Otherwise, the separator space is 3. 


LP Tag 


LP (List Part) 


p>—:LP.list-part-text 


>< 


The list part (LP) tag identifies a comment or an 
explanation applying to a part of a list. This tag is 
only allowed in information areas and help areas. 
It can be placed anywhere within the list. 


The text following the LP tag starts at the left 
margin of the current level of the list. It is not 
numbered or lettered. When used with the 
ordered list (OL) tag, the LP tag does not interrupt 
or increase the ordered sequence. 


Example: List Part 


This example uses a list part tag to keep the flow 
of the list from being interrupted. 


UIM Source 


:ol. 

:1i.First item 

:Ip.This is a list part. 
:1i.Second item 

:eol. 


Results 
1. First item 
This is a list part. 


2. Second item 
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MBAR tag 


MBAR (Menu Bar) 


>—:EMBAR. 


>>— : MBAR—NAME=menu-bar-name ee 7 F > 
HELP=help-module-name I 1 
nemo 
3 


>< 


The menu bar (MBAR) tag defines a menu bar 
area of a panel. The menu bar appears as the 
topmost element in a panel and consists of one or 
more menu bar choices. When the user positions 
the cursor at a menu bar choice and requests the 
ENTER dialog command, the pull-down menu for 
the selected menu bar choice is displayed below 
the text for the menu bar choice. 


The resulting pull-down menu contains a selection 
field which has one or more pull-down choices. 
The user is allowed to choose only one pull-down 
menu choice. Each selection field has one or 
more pull-down menu choices. 


All menu bars must be defined after any condi- 
tional statements and before the key lists. 


When a menu bar is specified for a panel with a 
list action column, a slash (/) or country- 
designated selection character may be entered on 
the list action column to indicate the elements the 
menu bar choice is to act against. The slashes 
are processed in the same top-to-bottom pro- 
cessing as in normal list action processing. The 
slash (/) is not allowed on the extended action 
entry of an action list. 


Other tags can be nested within the MBAR tag. 
These tags are listed in the following table. This 
table defines the order in which the tags must 
appear and specifies on what page more informa- 
tion can be found for each tag. 
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Table A-15. Tag Allowed Between the MBAR and 
EMBAR Tags. 


Tag Name Order Page 


MBARC 1 A-110 
(Menu bar choice) 


Required Attribute 


NAME=menu-bar-name 
The name assigned to the menu bar. For 
more information on the rules for naming, see 
“Name Syntax” on page A-4. 


Optional Attributes 


HELP=help-module-name 
The name of the help information explaining 
the purpose of the menu bar. The help 
module name may be a name imported from 
another panel group, but must follow the rules 
for names outlined earlier in this chapter. For 
more information on the rules for names, see 
“Name Syntax” on page A-4. 


MAXBARL=1 | 2 | 3 
The maximum number of lines that can be 
used for the descriptions of the menu bar. 
From 1 to 3 lines can be specified; 1 is the 
default. Only as many menu bar lines as 
needed up to the maximum number allowed 
by MAXBARL are used. If all the menu bar 
choices do not fit in the number of lines speci- 
fied, a compiler error results. 


Example: Menu Bar 


This example defines the menu bar seen on the 
Work with Programs panel. 


UIM Source 


.* Menu bar for Work with Programs panel 
:mbar name=mbarpgm 
help='mbarpgm/ ' 


:pdfldc 


:pdfldc 


:pdfldc 


:pdaccel 
:epdfld. 
:embarc. 
x 

.* Menu 
:mbarc 


:pdfld. 
:pdfldc 


:pdfldc 


:pdfldc 


bar choice for the "File" pull-down 
help='mbarpgm/file' 


.File 


option=2 


help='mbarpgm/file/change' 
action='cmd ?CHGPGM PGM(&var2./&varl.)' 


actfor=list 
.Change 
option=4 


help='mbarpgm/file/delete' 
action='cmd DLTPGM PGM(&var2./&varl.) ' 


actfor=list 


confirm=confpgm 
usrexit='call exitpgm' 


.Delete 
option=5 


help='mbarpgm/file/display' 
action='cmd DSPPGM PGM(&var2./&varl.) ' 


actfor=list 
.Display 
option=6 


help='mbarpgm/file/exit' 


action=exit 
varupd=no 
eExit 

.F3 


bar choice for the "Help" pull-down 
help='mbarpgm/help' 


.Help 


option=1 


help='mbarpgm/help/helphelp' 
action=helphelp 


varupd=no 


-Help for help... 


option=2 


help='mbarpgm/help/help' 
action=exthelp 


varupd=no 


.Extended help... 


option=3 


help='mbarpgm/help/keyshelp' 
action=keyshelp 


varupd=no 


MBAR tag 


-Keys help... 

:pdfldc option=4 
help='mbarpgm/help/schidx' 
action=helpidx 
varupd=no 
-Help index... 

:pdfldc option=5 
help='mbarpgm/help/about ' 
action='call logopgm' 
varupd=no 
-About... 

sepdfld. 

:embarc. 

:embar. 


Results 


File Help 
Work with Programs 
System: SYSTEMO1 
Select items in list, press F10 to select action. 


Opt Program Library Text 

PPPPPPPPP1 LLLLLLLLLL Description text 
* — PPPPPPPPP2 LLLLLLLLLL Description text 
PPPPPPPPP3 LLLLLLLLLL Description text 
PPPPPPPPP4 LLLLLLLLLL Description text 


The File pull-down is displayed as shown below. 


File Help 
: 2. Change 5 Work with Programs 
o System: SYSTEMO1 
4. Delete : ress F10 to select action. 
5. Display 5 
6. Exit F30: Text 


y 
Leseencseenceeesceee: LLLL Description text 
PPPPPPPPP2 LLLLLLLLLL Description text 
PPPPPPPPP3 LLLLLLLLLL Description text 
PPPPPPPPP4 LLLLLLLLLL Description text 


The Help pull-down is displayed as shown below. 


File Help 
1. Help for help... : with programs 
: 2. Extended help... : System: SYSTEMO1 
Select : 3. Keys help... : select action. 
: 4. Help index... B 
Opt Pr: 5. About... : 
PR siasc- ste ayetshetay Fels sie Fie. eae eres Pe PELON: LEXE 


PPPPPPPPP2 LLLLLLLLLL Description text 
PPPPPPPPP3 LLLLLLLLLL Description text 
PPPPPPPPP4 LLLLLLLLLL Description text 


When F10 (ACTIONS) is pressed, the cursor is 
positioned in the space before the first menu bar 
choice. 


When a menu bar choice is selected, the cursor is 
located at the pull-down field and the tab key 
moves to the first unselected menu bar choice. 
Repeated pressing of the tab key moves the 
cursor through the menu bar area and then back 
to the pull-down menu. 
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MBARC tag 


MBARC (Menu Bar Choice) 


>>— : MBARC—HELP=he lp-module-name—.—menu-bar-choice-text—: EMBARC. >< 


The menu bar choice (MBARC) tag defines one 
choice within a menu bar. The end of the menu 
bar choice must be indicated with an EMBARC 

tag. 


Other tags can be nested within the MBARC tag. 
These tags are listed in the following table. This 
table defines the order in which the tags must 
appear and specifies on what page more informa- 
tion can be found for each tag. 


Table A-16. Tags Allowed Between the MBARC and 
EMBARC Tags. 


Tag Name Order Page 
PDFLD 1 A-133 
(Pull-down field) 

PDFLDC 2 A-134 


(Pull-down field choice) 


Required Attributes 


HELP=help-module-name 
The name of the help information explaining 
the purpose of the menu bar choice. The help 
module name may be a name imported from 
another panel group, but must follow the rules 
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for names outlined earlier in this chapter. For 
more information on the rules for names, see 
“Name Syntax” on page A-4. 


Required Text 


menu-bar-choice-text 
The displayable description for the menu bar 
choice. The text must appear on the same 
line or the next line as the tag, the text can 
contain only the reverse text (RT) tag, and the 
text must be no longer than 32 bytes. 


The menu bar is formed by concatenating the 
text from the various menu bar choices. If the 
text does not fit on the rest of a line, it is 
placed on the next line. The menu bar is 
limited to the number of lines specified on the 
MAXBARL attribute on the MBAR tag. 


The text is displayed with a tabable space in 
front of it. When the tab keys are used to 
position the cursor at one of the menu bar 
choices, the cursor appears one character to 
the left of the text. Two spaces are placed 
between each text field for the menu bar. The 
visual result has three spaces between 
choices. 


MENU Tag 


MENU (Menu Area) 


>>—: MENU—DEPTH= fein i 
ty! 
BOTSEP= 


> 


> EMENU. 


sace, | | | 
None— scroLt=—Lyes 


RULE 


Loeneitie 


>< 


The menu area (MENU) tag defines a menu area. 
This tag is allowed only for display panels. The 
end of the menu area must have a EMENU tag. 


The menu area is included in the panel with all the 
other areas that are defined on the panel. Only 
one menu area may be present on any panel. 


Either the command line (CMDLINE) tag or the 
option line (OPTLINE) tag must be specified for a 
menu panel. The user selects a menu option by 
entering the option number on the command line 
or option line. 


Other tags can be nested within the MENU tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-17. Tags Allowed Between the MENU and 
EMENU Tags 


Tag Name Order Use Page 
TOPINST 1 D A-161 
(Top instruction 

line) 

APPFMT 2 D A-8 


(Application for- 
matted area) 


Table A-17. Tags Allowed Between the MENU and 
EMENU Tags 


Tag Name Order Use Page 


MENUGRP 3 D 
(Menu column 
group) 


A-114 


MENUI 3 D 
(Menu item) 


A-115 


BOTINST 4 D 
(Bottom instruc- 
tion line) 


A-10 


Required Attribute 


DEPTH=area-depth | '*' 
The depth of the area in lines, including sepa- 
rators if any are specified. 


If '*' is specified, the space remaining on the 
display after everything else is allocated is 
given to this area. Only one area in the panel 
may have '*' coded. 


Optional Attribute 


BOTSEP=SPACE | NONE | RULE 
Defines the bottom separator for the menu 
area. If SPACE is specified, a line of spaces 
is used. 


NONE indicates that no separator line exists. 


If RULE is specified, a line of underscored 
spaces is used as a separator line. 


SCROLL=NO | YES 
NO indicates that the menu is not scrollable. 


YES indicates that the menu area is intended 
to be scrollable. Ordinarily YES should not be 
used, but longer, scrollable menus can be 
constructed with SCROLL=YES. Fora 
SCROLL=YES area, a line of spaces is used by 
the UIM to provide a line for the scroll infor- 
mation. If BOTSEP=SPACE is also specified on 
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MENU Tag 


this tag, only one line of spaces is used (— 
unless this area also contains bottom aM Mymaln Ben 
instructions Select one of the following: 


1. Display menu X 
2. System operations 


90. Sign off 


Optional Text 


area-title 
The title of the area. If no text is specified, no 
title line is allocated to the area. The text 
must appear on the same or next line as the Selection or conmand 


tag, the text can contain only the reverse text 
(RT) tag, and cannot exceed a maximum 


F3=Exit F4=Prompt F9=Retrieve F12=Cancel 


length of 55 characters. 


Example 2: Menu Area with 


Example 1: Simple Menu Area 
P P Groups 


This example defines a menu area with three 


options. This example has three menu areas, each of 


UIM Source 


:panel name=main 
help='menu/main' 
keyl=smal1 
panel id=zmenu 
topsep=space 
.My Main Menu 

:menu depth='*'. 

:topinst.Select one of the following: 

:menui help=MNUSER 
option=1 
action='MENU X' 
.Display menu X 

:menui help=MNSYS 
option=2 
action='MENU SYSOPR' 
.System operations 

:menui help=MNOFF 
option=90 
action='CMD SIGNOFF' 
-Sign off 

:emenu. 

:cmdline size=long.Selection or command 

:epanel. 


Results 
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which has options that can be chosen. 


UIM Source 


:panel name=cfg2 
help='menu/cfg2' 
panel id=zmenu 
keyl=smal] 
.Configuration Templates 
smenu depth='*'. 
:topinst.Select one of the following: 
:menugrp.Local Hardware: 
:menui help='opt/1cl/wsprt' 
option=1 
action='MENU LCLWSPRT' 
-Work stations and printers 
:menui help='opt/1cl/ctl' 
option=2 
action='MENU LCLCTL  ' 
.Controllers 
:menui help='opt/1cl/tapdkt' 
option=3 
action='MENU LCLTAPDKT' 
-Tape drives and diskette drives 
:emenugrp. 
:menugrp.Remote Hardware: 
:menui help='opt/rmt/wsprt' 
option=4 
action='MENU RMTWSPRT' 
-Work stations and printers 
:menui help='opt/rmt/ctl' 
option=5 
action='MENU RMTCTL ' 
.Controllers 
:menui help='opt/rmt/tapdkt' 
option=6 
action='MENU RMTTAPDKT' 


.Tape drives and diskette drives 
:emenugrp. 
:menugrp.Communications Support: 
:menui help='opt/cmn/lines' 
option=7 
action='MENU CMNLINES' 
.Communications lines 
:menui help='opt/cmn/ctl ' 
option=8 
action='MENU CMNCTL ' 
.Communications controllers 
:emenugrp. 
:emenu. 
:cmdline size=long.Selection or command 
:epanel. 


Results 


MENU Tag 


CFG2 Configuration Templates 
Select one of the following: 


Local Hardware: 
1. Work stations and printers 
2. Controllers 
3. Tape drives and diskette drives 


Remote Hardware: 
4. Work stations and printers 
5. Controllers 
6. Tape drives and diskette drives 


Communications Support: 
7. Communications lines 
8. Communications controllers 


Selection or command 
=e=> 


System: 


; 


XXXXXXXX 


F3=Exit F4=Prompt F9=Retrieve F12=Cancel 


bes 
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MENUGRP Tag 


MENUGRP (Menu Group) 


>>—:MENUGRP 
Lconp=condi t toh-nane=| 


sp pie-headinoe 


: EMENUGRP. >< 


The menu group (MENUGRP) tag groups menu 
items of a menu area together and supplies a 
heading for the group. This tag is allowed only for 
display panels. 


If the number of lines required to display the first 
two items of the menu group exceeds the number 
of lines remaining in the current page, the entire 
group is forced to the next page. When all items 
in the menu group are not completely displayed 
on one page, the group is continued onto as many 
pages as required to display all items. 


Other tags can be nested within the MENUGRP 
tag. These tags are listed in the following table. 
The table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
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number of three cannot precede a tag with an 
order number of one or two. 


Table A-18. Tag Allowed Between the MENUGRP 
and EMENUGRP Tags 


Tag Name Order Use Page 
MENUI 1 D A-115 
(Menu item) 


Optional Attribute 


COND=condition-name 
The group is displayed and active on the 
panel only if the condition specified is true. If 
the condition is false, the entire group is not 
shown. The condition must be defined in the 
panel group prolog with the condition definition 
(COND) tag. 


Optional Text 


group-heading 
The heading placed above the menu items of 
the group. The text must appear on the same 
or next line as the tag and can only contain 
the reverse text (RT) tag. The group heading 
always appears on one display line beginning 
in column four. 


MENUI or MI Tag 


MENUI or MI (Menu Item) 


>>—:MENUI or MI—HELP=help-module-name—OPTION=opt ion-number—ACTION='action-text '_——» 


> > 
LvAME=menu- i inne Lconp=condi t fencianes| Laval L=condit fonsnane 
> > 
Lay LMSGID=message-ident ee Lavimse F=qualified-message-fi re snome 
> > 
LwARKER=condi t icine. LiteM=dialog- daviahienomed! 
>< 


. | 
Le resniae MomLGeser EDEL On texe 


Required Attributes 


HELP=help-module-name 


Identifies online information explaining the 
purpose of the menu item. The help module 
name may be a name imported from another 
panel group, but must follow the rules for 
names outlined earlier in this chapter. For 
more information on the rules for names, see 
“Name Syntax” on page A-4. 


The online information identified by this attri- 
bute is displayed when help is requested while 
the cursor is positioned on the text for this tag 
or while the cursor is on the command or 
option line and a valid menu item number has 
been entered. 


OPTION=option-number 


The number to assign this option. Option 
numbers are integers in the range 0 through 
999. 


The menu items are displayed in the order 
defined for the menu area. If the numbering 
of two items is not consecutive, a blank line is 
automatically placed between the two items. 


ACTION=' action-text' 


The action occurring when the menu item is 
selected by the user. The valid forms of 
action-text are: 


¢ ‘CALL program-reference' 

¢ 'CANCEL' 

¢ ‘CMD commano-string' 
Any dialog variable name in the command 
string must be preceded by an ampersand 
and should be ended with a period to 
denote variable substitution. 

e ‘EXIT’ 


e ‘MENU qualified-menu-name 
RTNPNT/NORTNPNT' 
e ‘RETURN positive-integer' 


For a description of each of these actions, see 
Appendix B, “UIM Dialog Commands” on 
page B-1. 


Optional Attributes 


NAME=menu-item-name 
The name associated with the menu item. 
This name can be used with the Add Pop-Up 
Window (QUIADDPW) API to position a 
window near this menu item. For more infor- 
mation on the rules for naming, see “Name 
Syntax” on page A-4. 


COND=condition-name 
The menu item is in effect on the panel only if 
the condition specified is true. The condition 
must be defined in the panel group prolog with 
the condition definition (COND) tag. 


AVAIL=condition-name 
The name of a condition indicating to the UIM 
whether or not the menu item is available for 
selection by the user. The condition must be 
defined in the panel group prolog with the 
COND tag. 


Unavailable menu items are displayed with an 
asterisk (*) overlaying the first part of the 
menu item number. 


When the condition is true, the menu item is 
available. When the condition is false, the 
menu item is not available. Any condition 
specified on the COND attribute of this tag takes 
precedence over this attribute. 
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MENUI or MI Tag 


AVLMSGID=message-identifier 


The message identifier of the message dis- 
played when the pull-down choice is selected 
but is not available as specified by the AVAIL 
attribute of this tag. This attribute is allowed 
only when the AVAIL attribute is specified. 


If this attribute is not specified, the UIM dis- 
plays a default message stating that the 
choice is currently not available. 


AVLMSGF= ' qualified-message-file-name' 


The message file name containing the 
message identifier. This attribute is allowed 
only when the AVLMSGID attribute is specified 
on this tag. If the DFTMSGF attribute is not 
specified on the panel group (PNLGRP) tag, 
and if the AVLMSGID attribute is specified on 
this tag, then this attribute must be specified. 


MARKER=condition-name 


The name of a condition indicating whether or 
not the menu item is marked with a greater 
than sign (>). The marker is displayed only if 
the condition specified is true. The condition 
must be defined in the panel group prolog with 
the COND tag. 


When the condition is true, a greater than sign 
is displayed to the left of the option number of 
the menu item. When the condition is false, 
the line is blank before the option number of 
the menu item. If this attribute is omitted, no 
marker appears on the menu item. 
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ITEM=dialog-variable-name 


The name of a dialog variable containing the 
text for the menu item description when the 
panel is displayed. The dialog variable may 
be defined with a BASETYPE of CHAR, IGC, or 
BIN on the class definition (CLASS) tag. The 
declared length of the dialog variable must be 
no longer than what fits on one line of the 
panel, starting in column 10. Allowance must 
be made if there is an application formatted 
area. 


If this attribute is used, no menu-item- 
description-text can be specified after the 
period for this tag. 


Optional Text 


menu-item-description-text 


The descriptive text accompanying the option 
and shown on the menu. The text may 
appear on more than one line in the source. 
The text can contain only the reverse text 
(RT) tag, and cannot exceed 70 characters in 
length. 


The item description text begins in column 10 
of the panel. The option number, a period, 
and one blank appear immediately before the 
item description text. The item number begins 
in column 7, 6, or 5, depending on whether 
the option number has 1, 2, or 3 digits. The 
text is formatted onto additional lines as nec- 
essary, and the additional lines are not 
indented two spaces to fit on the panel. 


NT or NOTE Tag 


NT or NOTE (Note) 


>>—:NT. or :NOTE. fs J 
note-text 


:ENT. or :ENOTE. Pd 


The note (NT) tag identifies a single- or multiple- 
paragraph note. This tag must have a matching 
end tag. You can also use :NOTE and :ENOTE in 
place of the :NT and :ENT tags. These tags are 
only allowed in information areas and help areas. 
Notes cannot be nested. 


Notes can occur anywhere in text that a para- 
graph is allowed. They can contain any basic text 
items, but cannot contain headings, figures, lines, 
examples, or any type of list. If this tag has not 
been ended when a heading tag is encountered, 
the note ends and a warning message is issued 
by the compiler. 


The note is an implied paragraph. It is formatted 
as a block and indented 6 spaces from the current 
margin. The word Note, formatted in highlight 
phrase 2 (HP2) and followed by a colon, begins 
the paragraph. There are two spaces between 
the note tag and the text if either the note tag or 
the text are single-byte characters. There are four 
spaces between the note tag and the text if both 
are double-byte characters. 


A note is aligned with the text of a list item when 
used within a list. 


Other tags can be nested within the NOTE tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-19. Tags Allowed Between the NOTE and 
ENOTE Tags 


Tag Name Order Use Page 
P 1 B A-121 
(Paragraph) 

PC 1 B A-131 
(Paragraph con- 

tinuation) 


Optional Text 


note-text 
Although the text of the note is not required, 
the tag has no meaning when text is not spec- 
ified. 


Example: Using a Note 


The note tag makes important information stand 
out in a paragraph, as in this example. 


UIM Source 


:P.Here's a paragraph. 

:NT. 

Here's the first paragraph 
of the note. 

Ps. 

Here's the second paragraph 
of the note. 

sENT. 

:P.Here's a paragraph. 


Results 
Here's a paragraph. 


Note: Here's the first paragraph of the 
note. 


Here's the second paragraph of the note. 


Here's a paragraph. 
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OL, LI Tags 


OL (Ordered List) 


p>—:0L LC Bie t :LI.item-text | : EOL. >< 
COMPACT: 
The ordered list (OL) tag identifies an ordered list ifies on which page more information can be found 
of items. It requires a matching end tag. These for each tag. 
tags are only allowed in information areas and 
help areas. When more than one tag is listed with the same 
order number, all tags of that number can be 

Ordered lists can occur anywhere in text and can mixed in any order. However, a tag with a higher 
be nested within other lists. order number cannot precede a tag with a lower 


order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Note: Care should be taken when using unfor- 
matted lines (LINES), figure (FIG), and example 
(XMP) tags within ordered lists, because text that 
does not fit on one line wraps to column one of 


; ; ; Table A-20. Tags Allowed Between the OL and EOL 
the next line. Lines and figures start at the current 


Tags 
left margin, and examples are indented four 
spaces from the current left margin. The current sed: Name pide 108s nade 
left margin changes when nested lists are for- FIG 1 B A-59 
matted. If online help information has the LINES, (Figure) 
FIG, or XMP tag imbedded at various locations, LINES 1 B A-77 
including within lists, it may not look the same (Unformatted 
each time. lines) 
XMP 1 B A-171 
The OL tag is formatted as a hanging, indented (Example) 
list, with the item identifier (1,2,...a,b,...) at position 
: ‘ . NT 1 B A-117 
four relative to the left margin. The text begins at (Note) 
position eight relative to the left margin. 
P 1 B A-121 
Ordered lists are identified in a formatted docu- (Paragraph) 
ment by sequential numbers or letters, depending PC 1 B A-131 
on the definition for each level. The levels of defi- (Paragraph con- 
nition are as follows: tinuation) 
hs Wes Bas ed 12s 08, LP 1 B A-107 
Bs Be Ds. OF 4h ag Pi Aa DD 46.997 (List part) 
3. 1), 2), 3),...,11), 12), .. ., 99) OL 1 B A-118 
4. a), b), c),..., Z), aa), bb), . . ., zz) (Ordered list) 
SL 1 B A-152 
Any additional levels repeat the sequence from (Simple list) 
the beginning. UL ; B Aes 
Other tags can be nested within the OL tag. pboleereesy 
These tags are listed in the following table. The PARML 1 B A-129 
table defines the order in which the tags must (Parameter list) 
appear, indicates which tags can be used in DL 1 B A-57 
display panels only, print panels only, or both (Definition list) 


(specified by a D, P, or B, respectively), and spec- 
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Optional Attribute 


COMPACT 
This attribute formats the list without a blank 
line between items. 


Required Tag 


:LI.item-text 
The text for the list item. The text is preceded 
by a number or a letter and a period. 


Example: Ordered List 
This example has two ordered lists, one imbedded 


within the other. The second ordered list uses the 
COMPACT attribute. 


UIM Source 


OL, LI Tags 


Some normal text... 

201. 

:1i.First item (number) 
:01 compact. 

:1i.First item (letter) 
:11.Second item (letter) 
:eol. 

:11.Second item (number) 
:eol. 


Results 


Some normal text... 
1. First item (number) 


a. First item (letter) 
b. Second item (letter) 


2. Second item (number) 
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OPTLINE Tag 


OPTLINE (Option Line) 


p>>—: OPTLINE 
LyaMe=option-l ine cname= 


Laas eenctaneeawe 


>< 


The option line (OPTLINE) tag specifies that a 
panel has a menu option field as opposed to a 
command line which allows commands or options 
to be entered. This tag is allowed only for display 
panels. The OPTLINE tag can be used only on a 
panel that has a menu area. 


Any text associated with this tag is used as an 
instruction line, appearing immediately above the 
option field on the panel. 


This tag must be the final tag in a panel, placed 
just before the EPANEL tag. The command line 
(CMDLINE) tag and the OPTLINE tag are mutually 
exclusive. 


Optional Attribute 


NAME=option-line-name 
The name associated with the option line. 
This name can be used with the Add Pop-Up 
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Window (QUIADDPW) API to position a 
window near the option line. For more infor- 
mation on the rules for naming, see “Name 
Syntax” on page A-4. 


Optional Text 


instruction-text 
The text appearing as instructions for the 
option line. This text is an implied paragraph. 


When the display is formatted, any text that 
does not fit onto one display line is formatted 
on the following blank lines and indented two 
columns. The text can be a maximum of 255 
characters and can contain only the reverse 
text (RT) tag. If no text is provided, no 
instruction line is allocated or displayed above 
the option line. 


P Tag 


P (Paragraph) 


p>—:P.paragraph-text 


>< 


The paragraph (P) tag identifies a paragraph, 
which is one or more sentences related by their 
subject matter. This tag is only allowed in infor- 
mation areas and help areas. 


Paragraphs can occur anywhere in text and can 
contain text items. A matching end tag is not 
allowed; a paragraph is ended by another para- 
graph or by a higher-level element. 


Each paragraph is formatted as a block of text 
without indenting the first line. One blank line 
separates paragraphs from other text items. 


Paragraphs inserted within a list align with the text 
of the list item. 


Optional Text 


Although the paragraph text is not required, the 
tag has no meaning when text is not specified. 


Example: Paragraph Tag 


This example illustrates how the paragraph tag is 
used. 


UIM Source 


:P.Here's a paragraph. 
Lines are formatted to 
fill the column. 
:P.Here's another 
paragraph. 


Results 


Here's a paragraph. Lines are formatted to 
fill the column. 


Here's another paragraph. 
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PANEL Tag 


PANEL (Display Panel) 


p>>— : PANEL—NAME=pane | -name—HELP=help-module-name—KEYL=key-list-name > 
> > 
PANEL D=@tatog=ver tab Pesnane=! LT iiLE=atologavartaple-nane) 
aera | | FIT: MBAR=menu-bar-name 
w1oTH=—L-panel-width DEPTH= | panel-depth 
| 1 | | SYSNAM | DATE=dialog-variable-name 
MSGL=—+—2 TOPSEP=——SPACE 
3 RULE 
4 DATETIME 
NONE 
> > 
LeTiiccdlaldovaniabteshanes | PNLGRP | ENTER='action-text = 
ENBGUI=——NO: 
YES 
de Els ies aa] ‘: 
SELECT='action-text' USREXIT='CALL program-reference' 
> > 
Leiteraen-eobleendne= Lesevanediatogsvariablecname= 
> > 
Lcsppos=dialog-variable-nane— Lee Ris teal ologevanieble-néne 
> > 
eCSREID=dinlogcvardablo-nane—| L cSRNAME=dialog-variable-name— 
> :EPANEL. | 
anette 
The display panel (PANEL) tag is opened using Table A-21. Tags Allowed Between the PANEL and 
the PANEL tag and closed using the EPANEL tag. EPANEL Tag 
It contains tags to define one or more panel area Tag Name Order Use Page 
definitions. DATA 1 D 31 
ie Dat ta- 
Other tags can be nested within the PANEL tag. es a : 
These tags are listed in the following table. The 
INFO 1 D A-68 


table defines the order in which the tags must 


appear, indicates which tags can be used in nofinationete) 


display panels only, print panels only, or both LIST 1 D A-82 
(specified by a D, P, or B, respectively), and spec- (List area) 
ifies on which page more information can be found MENU 1 D A-111 
for each tag. (Menu area) 

ot TEXT 1 D A-154 
When more than one tag is listed with the same (Text area) 
order number, all tags of that number can be 

CMDLINE 2 D A-26 


mixed in any order. However, a tag with a higher 


order number cannot precede a tag with a lower (Gotmmana tine) 


order number. For example, a tag with an order OPTLINE 2 D A-120 
number of three cannot precede a tag with an (Option line) 
order number of one or two. 


Required Attributes 
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NAME=panel-name 
The name of the panel. For more information 
on the rules for naming, see “Name Syntax” 
on page A-4. 


HELP=help-module-name 
The name of a help module containing the 
beginning of the extended help for the panel. 


KEYL=key-list-name 
The name of a key list for the panel. 


Optional Attributes 


PANELID=dialog-variable-name 
The name of a dialog variable containing the 
text for the panel identifier when the panel is 
displayed. The dialog variable must be 
defined on a class definition (CLASS) tag with 
BASETYPE='CHAR 10', 'NAME 10’, or 
‘OBJNAME 10'. The UIM displays the con- 
tents of the variable in the upper left corner of 
the panel. If this attribute is omitted, no panel 
identifier appears on the display. 


To specify a panel identifier for a menu 
created by using the Create Menu (CRTMNU) 
command, the dialog variable for ZMENU 
should be declared with PANELID=ZMENU on 
the PANEL tag. The value of the ZMENU 
dialog variable is displayed as the panel iden- 
tifier. 


TITLE=dialog-variable-name 
The name of a dialog variable containing the 
text for the panel title. The dialog variable 
must be defined with a display width of 55 or 
the width of the panel minus 2, whichever is 
less. A translation list may be used to provide 
the panel title. 


The UIM trims trailing blanks from the string 
and centers the resulting text in the panel title 
area of the display. If this attribute is used, no 
panel-title-text can be specified. 


For a pop-up panel, the declared length of the 
dialog variable must be equal to the width of 
the pop-up panel minus 2 bytes, and less if 
PANELID or TOPSEP=DATETIME is specified on 
this tag for the panel. 


WIDTH=80 | panel-width 
The width of the panel. If the width is not 
specified, the panel width defaults to 80 bytes. 
The specified width must contain 2 bytes of 
space for the left and right margins. A panel 


PANEL Tag 


with WIDTH=80 results in 78 bytes of space for 
panel data. 


The maximum width supported for a panel dis- 
played as a full screen is 132 bytes. The 
maximum width supported for a pop-up 
window depends on what size screen the 
device supports. On a device that supports 
24 rows by 80 bytes, 74 bytes is the 
maximum width of a pop-up window. Ona 
device that supports 27 rows by 132 bytes, 
126 bytes is the maximum width of a pop-up 
window. The minimum width for a pop-up 
window is 20 bytes. 


DEPTH=FIT | panel-depth 


The depth of the panel. If the depth is not 
specified, the panel depth defaults to FIT. If 
DEPTH=FIT, the UIM uses the depth of the 
device at display time to determine the depth 
of the panel. When DEPTH=FIT, the compiler 
verifies that all panel elements fit within 24 
lines. 


The specified depth includes: 


¢ One line for a panel title 

¢ One line of area data 

¢ One or two lines for function key 
descriptions 

¢ One line for the message line 


The maximum supported depth is 27 lines for 
a panel displayed in a full display. The 
maximum supported depth for a pop-up panel 
depends on what the display device can 
support. On a device that can only support 24 
rows by 80 bytes, the maximum depth of a 
pop-up window is 21 lines. On a device that 
can support 27 rows by 132 bytes, the 
maximum depth of a pop-up window is 24 
lines. 


The minimum allowed depth is 5 lines. 


MBAR=menu-bar-name 


The name of the menu bar used on the panel. 
This attribute is not allowed on confirmation 
panels or panels that will be used as pop-up 
windows. 


Menu bars are only allowed on panels defined 
with one of the following sizes: 


e WIDTH=80 or 132 bytes, and DEPTH=FIT 
e WIDTH=80 bytes, DEPTH=24 lines 
e WIDTH=132 bytes, DEPTH=27 lines 
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PANEL Tag 


MSGL=1 | 2|3| 4 
The number of message lines that should 
appear on this panel. One message line is 
the default. 


TOPSEP=SYSNAM | SPACE | RULE 
| DATETIME | NONE 
Defines the top separator for the panel. If 
SYSNAM is specified, the separator line con- 
tains only the system name. 


If SPACE is specified, a line of spaces is 
used. 


If RULE is specified, a line of underscored 
spaces is used. RULE cannot be specified if 
the MBAR attribute is specified on this tag. 


lf DATETIME is specified, the separator line 
contains the date and time from the dialog 
variables identified on the DATE and TIME attri- 
butes of this tag. DATETIME also causes the 
system name to be on the right side of the 
title line. When date and time is used as the 
top separator for the panel, it should not be 
used to provide a current time clock. This 
function should be used to show the date and 
time in which the important data on the panel 
is collected or generated. 


NONE indicates that no separator line exists. 


Values other than TOPSEP=SPACE or NONE 
may cause undesirable results when the panel 
width is less than 80. 


DATE=dlalog-variable-name 
The name of a dialog variable containing a 
date displayed on the top separator for the 
panel. This attribute is required when 
TOPSEP=DATETIME is specified on this tag. 
The dialog variable must be defined with 
BASETYPE='DATE' on the CLASS tag. 


TIME=dialog-variable-name 
The name of a dialog variable containing a 
time displayed on the top separator for the 
panel. This attribute is required when 
TOPSEP=DATETIME is specified. The dialog 
variable must be defined with 
BASETYPE='TIME' on the CLASS tag. 


ENBGUI=PNLGRP | NO | YES 
Specifies whether the panel is enabled for 
conversion to a graphical user interface (GUI) 
by a client program. 
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When ENBGUI=YES is specified, the UIM 
includes information about the layout and 
content of the panel in the 5250 data stream. 
This information is used by client programs to 
create the graphical interface on the client. 
Table A-22 describes the information that is 
included in the 5250 data stream: 


Table A-22. Layout of UIM finger print 


Byte Value and Description 

0 Hex 27 - Non-display attribute 

1 Hex 40 - Blank 

2 Hex 20 - Terminating attribute 

3 Reserved 

4 Hex 00 - Panel BIDI=-NONE or LTR 
Hex 40 - Panel BIDI=RTL 

5 Hex 00 - Panel does not contain a list area 
Hex 40 - Panel might contain a list area 

6 Hex 00 - Panel does not contain a menu 
area 


Hex 40 - Panel might contain a menu area 


7 Hex 00 - Panel does not contain a help 
area 
Hex 40 - Panel might contain a help area 


This includes the UIM Help (UH) panels as 
well as application panels containing a 
‘TEXT area (for example, InfoSeeker). 


8 Hex 00 - Panel does not contain any other 
areas 
Hex 40 - Panel might contain one or more 
other areas 


Other types of areas are :DATA (input 
and/or output), :INFO (similar to help). 


9 Hex 27 - Non-display attribute 
10 Hex 40 - Blank 
11 Hex 20 - Terminating attribute 


When ENBGUI=NO is specified, the UIM does 
not include the extra information in the data 
stream. 


ENTER=' action-text' 
The default enter action for the panel, occur- 
ring when the Enter key is pressed and no 
UIM-defined action, such as menu or action 
list processing, is necessary. If this attribute 
is omitted, the panel is redisplayed to the user 
with no message or error indication. The valid 
forms of action text are: 


¢ ‘CALL program-reference' 


For a description of the interface between 
the UIM and the program for a function 


key CALL, see the System API Reference. 


¢ ‘CMD commano-string' 
Any dialog variable name in the command 
string must be preceded by an ampersand 
to denote variable substitution. 

e¢ ‘MSG message-identifier [ qualified- 
message-file-name ]' 

e¢ ‘RETURN positive-integer' 


For a description of each of these dialog com- 
mands, see Appendix B, “UIM Dialog 
Commands” on page B-1. 


SELECT=' action-text' 


The default selection action for the panel, 
occurring when items are selected in a 
selection list or an action list and no action is 
selected from the menu bar. If this attribute is 
not specified, the panel is displayed to the 
user with no message or error indication. The 
valid forms of action text are: 


« ‘ACTIONS' 

e ‘MSG message-identifier [ qualified- 
message-file-name ]' 

« 'PULLDOWN' 

e¢ 'RETURN positive-integer' 


The PULLDOWN and ACTIONS dialog com- 
mands cannot be specified if the MBAR attribute 
is not specified on this tag. 


USREXIT=' CALL program-reference' 


A general exit program called each time the 
user presses a function key or the Enter key 
after dialog variables and list entries are 
updated and before any action specified on 
the key list item (KEY), list action (LISTACT), 
pull-down field choice (PDFLDC), or menu 
item (MENUI) tag is performed. 


The program is passed parameters that 
include what function is requested by the user. 
The exit program may do application-defined 
validity checks, change the display position 
attribute of lists that appear on the screen, or 
both. If the exit program sends a CPF6A02 
status message to the UIM, the UIM redis- 
plays the panel without performing the normal 
action processing. 


The panel is redisplayed without calling this 
exit program if validity check errors associated 
with the CLASS, validity checking (CHECK), 
or translation list (TL) tags are detected, or if 


PANEL Tag 


the user presses an inactive function key. If 
the user presses a function key defined with 
VARUPD=NO on the KEY!I tag, the values 
entered on the panel by the user are not avail- 
able to this program. They are only stored 
internally in the UIM. 


For a description of the CALL dialog 
command, see Appendix B, “UIM Dialog 
Commands’ on page B-1. 


For a description of the interface between the 
UIM and the general exit program, see the 
System API Reference. 


TT=truth-table-name 


The name of a truth table defined by the truth 
table (TT) tag, specifying what combinations 
of truth values may occur for conditions 
defined by condition definition (COND) tags 
while the application is running. 


The table specified may contain any subset or 
superset of the conditions referred to by tags 
in the panel definition. Only the truth value 
combinations specified in the table, aug- 
mented by worst-case assumptions for any 
truth values not specified in the table, are con- 
sidered in evaluating whether or not the panel 
definition is usable. The table should not 
exclude any truth value combination that could 
occur when the panel is displayed. If a valid 
truth value combination is omitted, a panel 
group object may create without error and 
have undesirable results when panels are dis- 
played. For example, the UIM may fail to 
show panel elements that are conditioned-on 
for display. For more information about truth 
tables, see “TT (Truth Table)” on page A-162. 


If this attribute is omitted, all combinations of 
truth values are considered possible. This 
causes the tag language compiler to make 
worst-case assumptions for all conditions in 
evaluating whether or not the panel definition 
is valid. 


CSRVAR=dialog-variable-name 


This attribute must name a CHAR 10 dialog 
variable which is used by the UIM to contain 
either the name of the dialog variable or the 
name of the command line where the cursor is 
or will be positioned. 


The UIM updates this variable after the panel 
is displayed and before the general exit 
program or any action routines are called. It 
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PANEL Tag 


contains the name of the dialog variable asso- 
ciated with the field, or the name of the 
command line (if named) where the cursor is 
positioned on exit from the panel. If the 
cursor is not in a field or on a named 
command line, the CSRVAR dialog variable is 
set to blanks. 


The Display Panel (QUIDSPP) API supports 
an option that allows the application program 
to control the initial cursor position by setting 
the dialog variables associated with the 
CSRVAR, CSRPOS, CSRLST, and CSREID panel 
attributes before the panel is displayed. If the 
CSRVAR dialog variable does not contain the 
name of a dialog variable or command line 
displayed on the panel, the UIM default cursor 
positioning is used and no error is reported. 


If a data item is defined using data item 
extenders, the CSRVAR attribute contains the 
name of the extender dialog variable if the 
cursor is positioned within the extender field. 
If the cursor is positioned between fields, 
CSRVAR is set to the name of the dialog vari- 
able specified on the VAR attribute of the data 
presentation area (DATA) tag, and the 
CSRPOS dialog variable is set to zero. 


CSRPOS=dialog-variable-name 


This attribute must name a BIN 15 dialog vari- 
able used by the UIM to contain the character 
position within the field identified by the 
CSRVAR attribute on this tag where the cursor is 
or will be positioned. 


The UIM updates this variable after the panel 
is displayed, before the panel exit program or 
any action routines are called. It contains the 
position within a field where the cursor is posi- 
tioned on exit from the panel. If the cursor is 
not in a field, the dialog variable is set to zero. 
If the cursor is positioned in a text area asso- 
ciated with the field, such as a prompt label or 
column heading for a list area, the CSRVAR 
attribute contains the name of the dialog vari- 
able for the corresponding data item or list 
column, and the CSRPOS dialog variable is 
set to zero. 


The QUIDSPP API supports an option which 
allows the using program to control the initial 
cursor position by setting the dialog variables 
associated with the CSRVAR, CSRPOS, CSRLST, 
and CSREID attributes on this tag before the 
panel is displayed. If the CSRPOS attribute 
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identifies a position that is not valid for the 
display field, the UIM default cursor posi- 
tioning is used and no error is reported. 


CSRLST=dialog-variable-name 


This attribute must name a CHAR 10 dialog 
variable used by the UIM to contain the name 
of the list where the cursor is or will be posi- 
tioned. 


The UIM updates this variable after the panel 
is displayed, before the panel exit program or 
any action routines are called. It contains the 
name of the list associated with the list area 
where the cursor is positioned on exit from the 
panel. If the cursor is not in a list area, the 
dialog variable is set to blanks. 


The QUIDSPP API supports an option that 
allows the using program to control initial 
cursor position by setting the dialog variables 
associated with the CSRVAR, CSRPOS, CSRLST, 
and CSREID attributes of this tag before the 
panel is displayed. If the CSRLST attribute is 
not blank and does not contain the name of a 
list displayed on the panel, the UIM default 
cursor positioning is used and no error is 
reported. 


CSREID=dialog-variable-name 


This attribute must name a CHAR 4 dialog 
variable used by the UIM to contain the list 
entry handle within the list identified by the 
CSRLST attribute where the cursor is or will be 
positioned. 


The UIM updates this variable after the panel 
is displayed, before the panel exit program or 
any action routines are called. It contains the 
list entry identifier where the cursor was posi- 
tioned on exit from the panel. If the cursor 
was not in any list entry, the CSREID dialog 
variable is set to X'00'. If the cursor was 
positioned in a text area associated with a list 
column, such as a column heading, the 
CSRLST attribute contains the name of the cor- 
responding list and the CSREID dialog vari- 
able is set to X'00'. 


The QUIDSPP API supports an option that 
allows the using program to control the initial 
cursor position by setting the dialog variables 
associated with the CSRVAR, CSRPOS, CSRLST, 
and CSREID attributes of this tag before the 
panel is displayed. If the CSREID attribute 
identifies an unusable position that does not 
specify a list entry displayed on the panel, the 


UIM default cursor positioning is used and no 
error is reported. 


CSRNAME=dialog-variable-name 
This attribute must name a CHAR 10 dialog 
variable used by the UIM to contain the name 
of the item where the cursor is positioned. 


The UIM updates this variable after the panel 
is displayed, before the panel exit program or 
any action routines are called. It contains the 
name of the item where the cursor is posi- 
tioned on exit from the panel. If the cursor 
was not on any item, the CSRNAME dialog 
variable is set to blanks. 


The value of this variable may be used to 
position pop-up windows adjacent to a field 
using the Add Pop-Up Window (QUIADDPW) 
API. 


Optional Text 


panel-title-text 
The title used on this panel. The text must 
appear on the same or next line as the tag. 
The text cannot contain other tags, and is 
limited in length based on the width of the 
panel. The panel-title-text may be no more 


PANEL Tag 


than 55 bytes long and is required unless the 
TITLE attribute is specified on this tag. 


Example: Panel Definition 


This example defines a panel and sets up the ele- 
ments used within the panel. 


UIM Source 


:panel name=main 
help=hmain 
panel id=zmenu 
keyl=smal] 
.My Main Menu 
:menu depth='*'. 
:topinst.Select one of the following: 
:menui help=MNUSER option=1 
action='CMD MENU X' 
.Display menu X 
:menui help=MNSYS 
option=2 
action='CMD MENU SYSOPR' 
.System operations 
:menui help=MNOFF 
option=90 
action='CMD SIGNOFF' 
-Sign off 
:emenu. 
:cmdline size=long.Selection or command 
:epanel. 
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PANEL Tag 


Results 


A-128 Application Display Programming V4R1 


MAIN My Main Menu 


System: 


Select one of the following: 


1. Display menu X 
2. System operations 


90. Sign off 


Selection or command 
=E=> 


SYSTEMO1 


F3=Exit F4=Prompt F9=Retrieve F12=Cancel 


; 


PARML, PT, PD Tags 


PARML (Parameter List) 


pr: PARML.—-: PT.parameter-term—: Pi deserentign EPARML. >< 


The parameter list (PARML) tag identifies param- 
eter terms and descriptions. These tags are only 
allowed in information areas and help areas. This 
tag requires a matching end tag. The terms 
defined and their definitions are identified by the 
parameter term (PT) tag and the parameter defi- 
nition (PD) tag, respectively. 


Note: Care should be taken when using unfor- 
matted lines (LINES), figure (FIG), and example 
(XMP) tags within parameter lists because text 
that does not fit on one line wraps to column one 
of the next line. Lines and figures start at the 
current left margin, and examples are indented 
four spaces from the current left margin. The 
current left margin changes when nested lists are 
formatted. If there is online help information con- 
taining lines, figures, or examples imbedded at 
various locations, including within lists, it may not 
look the same each time. 


Parameter lists can occur anywhere in text; they 
can be nested within other lists, and other lists 
can be nested within parameter lists. Two PT or 
two PD tags cannot be used consecutively. 


Nested PARML tags increase the current left 
margin by four. 


Other tags can be nested within the PARML tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-23. Tags Allowed Between the PARML and 
EPARML Tags 


Tag Name Order Use Page 
FIG 1 B A-59 
(Figure) 

LINES 1 B A-77 
(Unformatted 

lines) 

XMP 1 B A-171 
(Example) 

NT 1 B A-117 
(Note) 

P 1 B A-121 
(Paragraph) 

PC 1 B A-131 
(Paragraph con- 

tinuation) 

LP 1 B A-107 
(List part) 

OL 1 B A-118 
(Ordered list) 

SL 1 B A-152 
(Simple list) 

UL 1 B A-164 
(Unordered list) 

PARML 1 B A-129 
(Parameter list) 

DL 1 B A-57 


(Definition list) 


Required Tags 


PT.parameter-term 
The parameter term. The term formats in 
highlight phrase 2 (HP2) and can contain the 
programming keyword (PK) or programming 
variable (PV) tags. 


The term appears on a line by itself, starting 
at position four relative to the current left 
margin. 


PD.parameter-description 
The description of the parameter. It can also 
contain the PK and PV tags. 
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PARML, PT, PD Tags 


The definition is printed on the following line, UIM Source 
with the paragraph indented eight spaces from 
; : . ; :PARML. 

the current left margin. It is an implied para- “PT. TERM 

graph and can contain any text items. Addi- :PD.This is a description of 

tional paragraphs can be inserted following the korn: = PK: Tern<EPK: is 

the description paragraph by using the para- a programming keyword. 

graph tag. :PT.:PK def.DEFAULT:EPK. 
:PD.This is a sample default 

Example: Parameter List parameter. 


:PT.:PV.variable:EPV. 
:PD.This is a parameter variable. 


This exampl arameter list to define 
s example uses a p - EPARML.. 


terms or parameters. 


Results 


TERM 
This is a description of the term. Term 
is a programming keyword. 


DEFAULT 
This is a sample default parameter. 


variable 
This is a parameter variable. 
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PC Tag 


PC (Paragraph Continuation) 


p>>—:PC.paragraph-continuation-text 


>< 


The paragraph continuation (PC) tag identifies the 
continuation of a paragraph that has been inter- 

rupted by another document element. This tag is 
allowed only in information areas and help areas. 


A paragraph continuation usually occurs after a 
figure, example, or a list. It indicates that the fol- 
lowing text is a continuation of the paragraph 
interrupted by a figure, example, or list. 


A matching end tag is not allowed. A paragraph 
continuation is implicitly ended by another para- 
graph or by a higher-level element. 


Example: Paragraph 
Continuation 


The paragraph continuation tag continues the par- 
agraph after the interruption of an example. 


UIM Source 


:p.If you enter the following 
command 

:xmp. 

WRKSPLF 

:exmp. 

:pc.a listing of all my spool files 
appears on the 

terminal. 


Results 


If you enter the following command 
WRKSPLF 


a listing of all my spool files appears on 


the terminal. 
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PDACCEL tag 


PDACCEL (Pull-Down Accelerator) 


p>—:PDACCEL—.—accelerator-text >< 
The pull-down choice accelerator (PDACCEL) tag Required Text 
defines text to be displayed as the accelerator key 
for a pull-down choice. accelerator-text 

The displayable description for the accelerator 

This tag defines only the text displayed. It does key. The text must appear on the same or 
not automatically define the function key. It is next line as the tag. The text cannot contain 
your responsibility to define the function key with any other tags, and cannot exceed 4 bytes in 
the key list item (KEYI) tag to perform the action length. 


defined for the pull-down choice accelerator. The accelerator text is displayed to the right of 


its pull-down choice. The first character of 
each accelerator in the pull-down field is left- 
aligned two spaces after the longest text for 
any pull-down choice. 
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PDFLD tag 


PDFLD (Pull-Down Field) 


>>—:PDFLD 
LyaMe=pul l Aounsfrerg nena 


:EPDFLD. >< 


The pull-down field (PDFLD) tag defines a 
selection field within the menu bar pull-down. A 
pull-down field consists of one or more pull-down 
choices. The pull-down fields are formatted 
according to the IBM Systems Application Archi- 
tecture (SAA) basic interface. 


A single pull-down field can be defined for one 
menu bar choice between the menu bar choice 
(MBARC) and the EMBARC tags. The largest 
option number allowed for a pull-down choice is 
99. The number of pull-down choices allowed to 
be specified between the PDFLD tag and the 
EPDFLD tag is determined by how many choices 
fit on the screen, based on conditioning. The 
maximum number of pull-down choices active at 
one time is determined by what fits on a screen. 


Other tags can be nested within the PDFLD tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-24. Tags Allowed Between the PDFLD and 
EPDFLD Tags 


Tag Name 


Order Use Page 


PDACCEL 1 D A-132 
(Pull-down choice 
accelerator) 


PDFLDC 1 D A-134 
(Pull-down field 
choice) 


Optional Attribute 


NAME =pul!-down-field-name 
The name associated with the pull-down field. 
For more information on the rules for naming, 
see “Name Syntax” on page A-4. 
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PDFLDC tag 


PDFLDC (Pull-Down Field Choice) 


p>>—: PDFLDC—OPTION=opt ion-number—HELP=help-module-name—ACTION='action-text '-———__» 


> 
Lu l-down-choi 


ce-tex + 


> > 
I Sie ee | CONFIRM=internal-panel-name— 
ACTFOR=——LIST 

> > 
LUSREXIT=!CALL program-reference J Lvarupp-—-ves— 

NO 

a aly es aie yee 
COND=condition-name AVAIL=condition-name AVLMSGID=message-identifier 

> > 
EAViNSGES quate fed messdge=filesnane'—! L CHONCESHialogavarioble-name=! 

>< 


The pull-down field choice (PDFLDC) tag defines 
one choice within a pull-down field. A pull-down 
field consists of one or more pull-down choices. 


Required Attributes 


OPTION=option-number 
The number assigne 


numbers are integers in the range of 1 


through 99. Table A-25. Valid Action Text for ACTION Values 

The pull-down choices are displayed in the Dialog 

order defined in the pull-down field. If the command” | RCTEOR-PANED “ AGTEORSOatT 

numbering of two choices is not consecutive, CALL X X 

a blank line is automatically placed between CHGVIEW x 

the two choices. CMD Xx X 

CMDLINE Xx 

HELP=help-module-name DSPHELP X 

Identifies help information explaining the EXIT x 

purpose of the pull-down field choice. The EXTHELP Xx 

name of the help module may be a name Hie Ra te 

imported from another panel group, but must eae : 

follow the rules for names outlined earlier in MENU X 

this chapter. For more information on the RETRIEVE x 

rules for names, see “Name Syntax” on RETURN x x 


page A-4. 


played. 


ACTION=' action-text' 


choices. If the cursor is in the entry field and 
a valid choice has been entered when help is 
requested, the help for that choice is dis- 


The action occurring when the pull-down 


d to this option. Option 


choice is selected. 


The online information identified by this attri- 
bute is displayed when help is requested while 
the cursor is positioned on text for this tag. 
This online information is also included as part 
of the contextual help displayed when the 
cursor is positioned on the text for the menu 
bar choice for this pull-down menu, or when 
the cursor is positioned within the pull-down 
menu but not on the text for one of the 
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For a description of each of these actions, 
see Appendix B, “UIM Dialog Commands” on 
page B-1. 


Optional Attributes 
ACTFOR=PANEL | LIST 


If PANEL is specified, the pull-down choice 
performs actions against the whole panel. 


If LIST is specified, the pull-down choice per- 
forms actions against items in a selection list 
or in an action list. 


When LIST is specified on a pull-down choice 
and if the user has not selected a list to be 
processed, the pull-down choice is displayed 
with an asterisk (*) overlaying the option 
number to indicate that the pull-down choice is 
not available. 


CONFIRM=internal-panel-name 


The name of the confirmation panel displayed 
before the action is performed. This attribute 
is allowed only when ACTFOR=LIST and 
ACTION=CALL or ACTION=CMD is specified on 
this tag. The confirmation panel must give the 
user the option to confirm or not confirm the 
action. If the action is confirmed, the appro- 
priate actions from this tag are performed. If 
the action is not confirmed, none of those 
actions are performed. 


The confirmation panel must be another panel 
defined within this panel group. 


For a list of the recommended and required 
conventions for this attribute, see “Confirma- 
tion Panel Requirements” on page A-136 and 
“Confirmation Panel Conventions” on 

page A-136. 


USREXIT=' CALL program-reference' 


Specifies the exit program for the action list 
program called to update the list entries after 
the action defined in the ACTION attribute is 
performed. This attribute is allowed only 
when ACTFOR=LIST and ACTION=CALL or 
ACTION=CMD is specified on this tag. The 
program is passed information that includes 
the name of the list and an indication of 
whether the option succeeded or failed. 


For a description of the CALL dialog 
command, see Appendix B, “UIM Dialog 
Commands’ on page B-1. 


For a description of the interface between the 
UIM and the exit program for action lists, see 
the System API Reference. 


VARUPD=YES | NO 


This attribute is allowed only when PANEL is 
specified on the ACTFOR attribute for this tag. 
When ACTFOR=LIST is specified, variable pool 
updating is performed. If YES is specified, 
validity checking occurs and the variable pool 
is updated before the action takes place. 


PDFLDC tag 


If NO is specified, the action is performed 
immediately and no variable pool updating 
occurs. 


Dialog Command VARUPD Values 
CALL YES | NO 
CHGVIEW YES 

CMD YES | NO 
CMDLINE NO 

DSPHELP NO 

EXIT NO | YES 
EXTHELP NO 

HELPHELP NO 

KEYSHELP NO 

HELPIDX NO 

MENU YES 

RETRIEVE NO 

RETURN YES | NO 

Note: The default value is based on the 
ACTION attribute. The first value is the default 
value. 


COND=condition-name 


The pull-down choice is in effect on the panel 
only if the condition specified evaluates to 
true. The condition must be defined in the 
panel group prolog with the condition definition 
(COND) tag. When the choice is 
conditioned-off, it does not appear in the pull- 
down and the help for the choice is not 
included in requests to display help. 


AVAIL=condition-name 


The name of a condition used by the UIM to 
determine whether or not the pull-down choice 
is available. The condition must be defined in 
the panel group prolog with the COND tag. 


When the condition is true, the pull-down 
choice is available. When the condition is 
false, the pull-down choice is not available. 
Any condition specified on the COND attribute of 
this tag takes precedence over this attribute. 


Unavailable choices are displayed with a color 
change on color devices and an asterisk (*) 
overlaying the first part of the choice option 
number. 


AVLMSGID=message-identifier 


The message identifier of the message dis- 
played when the pull-down choice is selected 
when it is not available as specified by the 
AVAIL attribute. This attribute is allowed only 
when the AVAIL attribute is specified on this 
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PDFLDC tag 


tag. If this attribute is not specified, the UIM 
displays a default message stating that the 
choice is currently not available. 


AVLMSGF= ' qualified-message-file-name' 


The message file name containing the 
message identifier. This attribute is allowed 
only when the AVLMSGID attribute is specified 
on this tag. If the DFTMSGF attribute is not 
specified on the panel group (PNLGRP) tag, 
and if the AVLMSGID attribute on this tag is 
specified, this attribute must be specified. 


CHOICE=dialog-variable-name 


The name of a dialog variable containing the 
pull-down choice text to be displayed. The 
dialog variable must be defined with a width 
less than or equal to 32 bytes. If this attribute 
is used, no pull-down-choice-text can be spec- 
ified. 

Dialog variables must be defined with a 
BASETYPE of CHAR, IGC, or BIN on the class 
definition (CLASS) tag. 


The error state of the dialog variable is not 
used for determining the highlighting of the 
text. 


Special formatting for IGC. (The abbrevi- 
ation IGC is used in commands and keywords 
to represent double-byte character set func- 
tions.) When a dialog variable with a 
BASETYPE of IGC is specified on the CLASS 
tag, the UIM does special formatting. If the 
variable value begins with a shift-out character 
(X'0E'), the UIM shifts the value 1 byte to the 
left to preserve vertical alignment with choices 
on other lines. 


Optional Text 


pull-down-choice-text 


The descriptive text shown in the pull-down 
field. The text may appear on a single line in 
the source. The text can contain only the 
reverse text (RT) tag, and cannot exceed 32 
bytes in length. The pull-down-choice-text is 
required unless the CHOICE attribute is speci- 
fied on this tag. 


For a pull-down choice, the option number, a 
period, and one blank appears immediately 
before the choice description text. The 
NBRSHAPE attribute of the PNLGRP tag 
explains how option numbers are presented 
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when BIDI=LTR or when BIDI=RTL is speci- 
fied on the PNLGRP tag. 


Confirmation Panel Requirements 


The panel named on the CONFIRM attribute of this 
tag must follow these conventions: 


The ENTER attribute on the display panel 
(PANEL) tag of the confirmation panel should 
have 'RETURN 100' coded. This indicates to 
the UIM that the action is confirmed by the 
user. 


No ACTION attribute on a key list item (KEYI) 
tag can be assigned to the RETURN action, 
because the UIM is handling the display of the 
panel and is unable to interpret the returned 
value. 


The confirmation panel must have a list area. 


The list used as the confirmation list must not 
also be used on the action list panel. 


The confirmation panel must not have an 
action list, a command line, a menu area, or a 
menu bar. 


Confirmation Panel Conventions 


The panel named on the CONFIRM attribute of this 
tag should follow these conventions: 


It should have title text and top instructions as 
appropriate to describe the panel. 


It should have a single list area with a list defi- 
nition that contains the same (or a subset of) 
columns defined in the original action or 
selection list. 


The list should be scrollable. 


If the action list has multiple views, the confir- 
mation list should also have multiple views 
and the same dialog variable should be used 
for the view variable on both lists. The confir- 
mation panel should also have a function key 
defined for the CHGVIEW dialog command. 
This allows a change view operation on the 
confirmation panel to change the view of the 
action or selection list panel when it is redis- 
played. 


The confirmation panel should have function 
key definitions for the ENTER, CANCEL, 
PAGEUP, PAGEDOWN, HELP, and PRINT 
dialog commands. 


e If a general exit program is defined, it should 


avoid making changes to the list or condition 
values that affect the redisplay of the original 
panel. 


The list used on the confirmation panel should 
not be used on anything but a confirmation 
panel, because the UIM deletes and changes 
the contents of that list. If multiple confirma- 


PDFLDC tag 


tion panels are used within a UIM application, 
they can share the same list. 


Most of the online help information for the 
action list panel can be used for the confirma- 
tion panel, but separate help information 
should be provided for the action column and 
for the extended panel help. 
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PK Tag 


PK (Programming Keyword) 


pp—:PK 
Ler 


programming-keyword-text 


: EPK. > 


The programming keyword (PK) tag identifies a 
programming keyword. This tag is only allowed in 
information areas and help areas. It requires a 
matching end tag. 


A programming keyword can occur anywhere in 
text. It helps explain the elements of program- 
ming syntax and is frequently used within param- 
eter lists. For more information on parameter lists, 
see “PARML (Parameter List)” on page A-129, 


The PK and EPK tag phrase must be specified on 
word boundaries. If the two characters imme- 
diately following the EPK tag are a punctuation 
mark and a blank, the UIM automatically extends 
the emphasis attribute to include the punctuation 
mark. This allows the punctuation mark and the 
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text associated with it to be displayed with the 
same emphasis. 


Optional Attribute 


DEF 
Specifies that the programming keyword is a 
default value. The programming keyword 
formats in highlight phrase 2 (HP2) unless the 
DEF attribute is specified. If the DEF attribute is 
specified, the programming keyword formats 
as highlight phrase 3 (HP3). 


Required Text 


programming-keywora-text 
Specifies the programming keyword. 


PNLGRP Tag 


PNLGRP (Panel Group) 


>>— : PNLGRP _ z is > 
SCHIDX=qualified-object-name HLPSHELF=——LIST zs 
bookshelf-name 
> [ > 
NO | | SBCS 
ENBGUI= [yes TxTMoDE=—-DBCS 
TXTCHRID='character-set code-page' | NONE | 
BIDI= HiT] 
RTL 
I Bites DFTMSGF=qualified-message-file-name 
NBRSHAPE=——HINDI 
> ii 7 :EPNLGRP. >< 
SUBMSGF= ' qualified-message-file-name' 


The panel group (PNLGRP) tag begins the defi- 
nition of a panel group. Only one PNLGRP tag is 
allowed and a matching EPNLGRP tag is 
required. 


Other tags can be nested within the PNLGRP tag. 
These tags are listed in the following table. This 
table defines the order in which the tags must 
appear and specifies on which page more infor- 
mation can be found for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-26. Tags Allowed Between the PNLGRP and 
EPNLGRP Tags 


Tag Name Order Page 
COPYR 1 A-30 
(Copyright) 

ISCHSYN any A-72 
(Index search synonym) 

IMPORT 2 A-67 
(Import) 

CLASS 3 A-14 
(Class definition) 

VAR 4 A-166 


(Variable definition) 


Table A-26. Tags Allowed Between the PNLGRP and 
EPNLGRP Tags 


Tag Name Order Page 
VARRCD 5 A-169 
(Variable record defi- 

nition) 

LISTDEF 6 A-100 
(List definition) 

COND 7 A-27 
(Condition definition) 

TT 8 A-162 
(Truth table) 

MBAR 9 A-108 
(Menu bar) 

KEYL 10 A-76 
(Key list) 

PANEL 11 A-122 
(Display panel) 

PRTHEAD 11 A-142 
(Print head panel) 

PRTPNL 11 A-146 
(Print panel) 

HELP 11 A-60 


(Help module) 


Optional Attributes 


SCHIDX=qualified-object-name 
The index search object used when the index 
search function is requested from the help 
modules for panels defined in this panel 
group. If SCHIDX is not specified, the index 
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PNLGRP Tag 


search function is not accessible when help 
modules are displayed for panels in this panel 
group. This attribute has no effect on help 
modules defined in the panel group unless 
panels in the panel group use the help 
modules. This attribute is mutually exclusive 
with the HLPSHELF attribute. 


HLPSHELF=LIST | bookshelf-name 


Specifies the bookshelf to be used when 
InfoSeeker is requested from the help 
modules for the panels defined in the panel 
group. LIST indicates that the default list of 
books and bookshelves are to be used. If the 
HLPSHELF attribute is not specified, 
InfoSeeker is not accessible when help 
modules are displayed for the panels in the 
panel group. This attribute has no effect on 
help modules defined in the panel group 
unless panels in the panel group use the help 
modules. This attribute is mutually exclusive 
with the SCHIDX attribute. 


ENBGUI=NO | YES 


Specifies the default value for enabling a 
client program for all panels in the panel 
group. This attribute establishes the value 
when ENBGUI=PNLGRP is specified or 
defaulted on the PANEL tag. 


When ENBGUI=YES is specified for a panel, the 
UIM includes information about the layout and 
content of the panel in the 5250 data stream. 
This information is used by a client program to 
create the graphical interface on the client. 
Table A-22 on page A-124 describes the 
information that is included in the 5250 data 
stream. 


When ENBGUI=NO is specified for a panel, the 
UIM does not include the extra information in 
the data stream. 


TXTMODE=SBCS | DBCS 


Specifies whether a single-byte character set 
(SBCS) or double-byte character set (DBCS) 
is used in the tag text. If DBCS is specified, 
the tag text must have the shift-in or shift-out 
characters to indicate the start and end of 
DBCS text. 


A panel group object for which TXTMODE=DBCS 
is specified can only be used on a display 
station and system capable of handling DBCS 
information. An attempt to display a DBCS 
menu, open a DBCS panel group object, or 
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present DBCS help information on a device 
that does not support DBCS results in an 
exception. 


TXTCHRID=' character-set code-page' 


Specifies the character set and code page for 
SBCS text data in the panel group source. 
This information is used for synonyms defined 
using the index search synonym (ISCHSYN) 
tag. For more information on this tag, see 
“ISCHSYN (Index Search Synonym)” on 
page A-72. If this attribute is omitted, all text 
must be on the index search (ISCH) and 
ISCHSYN tags to be in the character set and 
code page specified by the QCHRID system 
value at the time the panel group is created. 


The TXTCHRID attribute specifies the code 
page and character set of the text information 
in the panel group source. It must not be con- 
fused with the CHRID parameter on the 
CRTPNLGRP command, which controls the 
way dialog variables with CHRID=PNLGRP 
specified on the class definition (CLASS) tag 
are handled when the dialog variable value is 
sent to or from the display station. 


BIDI=NONE | LTR | RTL 


Indicates the orientation of the panels in the 
panel group. NONE indicates that the panels 
in the panel group should be displayed in a 
single direction with a left-to-right orientation. 
NONE is the default and is required when 
TXTMODE=DBCS is specified on this tag. 


When BIDI=NONE is coded, the following 
items are ignored: 


e The NBRSHAPE attribute on this tag 

e The BIDI, NBRSHAPE, CONTXTREV, and 
SYMSWAP attributes on the CLASS tag 

¢ All reverse text (RT) tags 


LTR indicates that the panels in the panel 
group are bidirectional and should be dis- 
played with a left-to-right orientation. 


RTL indicates that the panels in the panel 
group are bidirectional and should be dis- 
played with a right-to-left orientation. 


When either LTR or RTL is specified for a 
panel group, the work station controller 
enables the hot key to flip the panel so that 
the user can flip the panel if necessary. 

When RTL is specified, the controller automat- 


ically flips all panels of the panel group as 
they are displayed. 


The normal use of LTR is for panels written in 
a left-to-right language with a small amount of 
right-to-left language text in it. The normal 
use of RTL is for panels written in a right-to- 
left language with a small amount of text in a 
left-to-right language. 


The UIM does not allow a LTR or RTL panel 
to be used on a display device that does not 
have the correct code page for bidirectional 
languages. Hebrew uses code page 424 and 
Arabic uses code page 420. 


The value of this attribute of all possible panel 
groups that can be reached through hypertext 
links should be the same. If they are not the 
same when a reference phrase is selected, 
the resulting screen or pop-up window may be 
displayed with the opposite orientation. 


NBRSHAPE=ARABIC | HINDI 


This attribute is ignored when BIDI=NONE is 
specified on this. The NBRSHAPE attribute con- 
trols the display shape of UIM-generated 
numbers. This attribute is ignored except 
when code page 420 (Arabic) is being used. 


When ARABIC is specified, the normal digits, 
X'FO' through X'F9', are used for numbers. 
ARABIC is the default. 


When HINDI is specified, the translation of 
digits is performed with a translation table 
defined for each national language. 


Digits that come from the panel group source 
or from messages are not affected by the 
NBRSHAPE attribute because they are expected 
to already be translated to the correct char- 
acter. The numbers that are affected by the 
NBRSHAPE attribute are: 


e Numbers generated by the UIM for menu 
items 


PNLGRP Tag 


¢ Numbers generated by the UIM for 
ordered list numbers 


e¢ Numbers generated by the UIM for pull- 
down field choices 


e Page number information on a print panel 
and printed help information 


Numbers that are not affected by the NBRSHAPE 
attribute are: 


e The digits used in the system name 

e Messages displayed on the message line 

¢ Copyright dates on the message line 

e Product number information on a print 
panel and in printed help information 


Because the Hindi zero looks like a period, 
the format of the number in front of a menu 
item or pull-down choice is 'n)' instead of 

'n.', where 'n' is the menu item or choice 
option number. 


DFTMSGF= qualified-message-file-name 


The default message file used when a 
message file is not specified for a message 
identifier on any of the following tags: 


CHECK Validity checking 
LISTDEF List definition 

TL Translation list 
DATASLTC Data selection field 
PDFLDC Pull-down field choice 
LISTACT List action 

MENUI Menu item 


If the corresponding message file attribute is 
not specified on any of these tags when the 
MSGID attribute is specified for this tag, this 
attribute is required. 


SUBMSGF= qualified-message-file-name 


The default message file used when a 
message file is not specified on the &msg 
symbol. 


Appendix A. UIM Panel Group Definition Language A-141 


PRTHEAD Tag 


PRTHEAD (Print Head Panel) 


p>>— : PRTHEAD—NAME=pane l -name E 7 > 
PRODINFO=dialog-variable-name 

> > 
SpRIDATESdtetog=variablexnane~| LSoRTTINES@iolog Vanes lecnaie=. 

> > 
ESErce-ay vibosvartabiesnames Ler eahenanT ecnanies eon 

WIDTH=——132 

> > 
LOR sdiatogavariaplesnane= Logg (ap=aidloge ani splecnones 

> : EPRTHEAD. >< 
re it je-text 


A print head panel (PRTHEAD) tag contains tags 
defining heading information and data used with a 
UIM print application. A print heading panel 
establishes the prolog section printed after the title 
line on the first page and the header data printed 
at the top of every page. The prolog and header 
sections can be made up of data and information 
areas. A PRTHEAD panel causes an automatic 
page eject. 


Other tags can be nested within the PRTHEAD 
tag. These tags are listed in the following table. 
The table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-27. Tags Allowed Between the PRTHEAD 
and EPRTHEAD Tags 


Tag Name Order Use Page 
DATA 1 P A-31 
(Data presenta- 

tion area) 

INFO 1 P A-68 
(Information area) 

PRTTRAIL 2 P A-148 


(Print trail) 
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Required Attribute 


NAME=panel-name 
The name of the print head panel. For more 
information on the rules for naming, see 
“Name Syntax” on page A-4. 


Optional Attributes 


PRODINFO=dialog-variable-name 
The name of a dialog variable containing the 
product information printed on the second title 
line of the print output. 


The dialog variable must be defined with a 
BASETYPE of CHAR or IGC on the class defi- 
nition (CLASS) tag, and the maximum width is 
22 bytes. 


PRTDATE=dlalog-variable-name 
The name of a dialog variable containing the 
date printed on the page title. If this attribute 
is specified, the PRTTIME attribute must also be 
specified on this tag. If this attribute is not 
specified, the UIM uses the current system 
date when the Open Print Application 
(QUIOPNPA) API or the Add Print Application 
(QUIADDPA) API is called. 


The dialog variable must be defined with a 
class that has a BASETYPE of DATE on the 
CLASS tag. 


PRTTIME=dialog-variable-name 
The name of a dialog variable containing the 
time printed on the page title. The dialog vari- 
able must be defined with a class that has a 
BASETYPE of TIME on the CLASS tag. If this 


attribute is specified, the PRTDATE attribute 
must also be specified on this tag. If this attri- 
bute is not specified, the UIM uses the current 
system time when the QUIOPNPA API or the 
QUIADDPA API is called. 


TITLE=dialog-variable-name 


The name of a dialog variable containing the 
text for the page title line. The dialog variable 
must be defined on a CLASS tag with a 
display width of 55. A translation list may be 
used to provide the panel title or the width of 
the panel minus two, whichever is less. The 
dialog variable may also be defined with a 
BASETYPE of CHAR 55 or IGC 55 on the 
CLASS tag. The UIM trims trailing blanks 
from the string and centers the resulting text 
in the page title area. If this attribute is used, 
no title-text can be specified. 


TT=truth-table-name 


The name of a truth table specifying what 
combinations of truth values may occur at run 
time when the panel head is formatted. 


The table specified on this tag may contain a 
subset of the conditions referred to by tags in 
the print head panel. Only the truth value 
combinations specified in the table, aug- 
mented by worst-case assumptions for any 
truth values not specified in the table, are con- 
sidered in evaluating whether or not the print 
head panel is valid. The table should not 
exclude any truth value combination that could 
occur when the print head panel is formatted 
at run time. If a valid truth value combination 
is omitted, a panel group object may create 
without error and produce undesirable results 
when panels are printed. 


If this attribute is omitted, all combinations of 
truth values are considered possible. This 
causes the tag language compiler to make 
worst-case assumptions for all conditions in 
evaluating whether or not the print head panel 


PRTHEAD Tag 


OBJ=dialog-variable-name 


The name of a dialog variable containing the 
name of the object whose information is 
printed on the title line of the printout. If this 
attribute is not specified, an object name is 
not printed. 


If the OBJLIB attribute on this tag is specified, 
the class for this dialog variable must be 
defined with a width of 10 characters. If the 
OBJLIB attribute is not specified, the class for 
this dialog must be defined with a width of 1 
to 21 characters. 


OBJLIB=dialog-variable-name 


The name of a dialog variable containing the 
name of the library where the specified object 
from the OBJ attribute on this tag is found. 
This library name is printed on the title line of 
the printout. If this attribute is not specified, a 
library name is not printed. 


You are responsible for the validity of the data 
contained in the 0BJ and OBJLIB attributes. 
The UIM does not perform validity checking 
on these variables. If only the OBJ attribute is 
specified, only the OBJ is printed. However, if 
only the OBJLIB attribute is specified, a 
message is issued at compile time. 


The class for this dialog variable must be 
defined with a width of 10 characters. 


Optional Text 
page-title-text 


The title used on the title line. The text must 
appear on the same line or next line as the 
tag. The text can only contain the reverse 
text (RT) tag, and cannot exceed 55 charac- 
ters in length. The page-title-text is required 
unless the TITLE attribute is specified on this 
tag. 


Layout of the Title Lines 

is valid. 

The title lines for the PRTHEAD tag appear on the 
top two lines of each printed page. The place- 
ment of fields in the title lines depends on the 
width specified on this tag. 


WIDTH=80 | 132 
Defines the width, in bytes, of the PRTHEAD 
panel. The default value is 80 bytes. 
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PRTHEAD Tag 


Table A-28. First Line of Heading with Print Width 132 


Table A-30. Second Line of Heading with Print Width 
132 


Start 
Data Column Length Start 
Title Sea Max. 55 Data Column Length 
note. Product information 1 22 
Separator See 4 Separator 23 Min. 55 
note. Library See Max. 10 
"Page" (with expansion) See Max. 11 note 
Hole. Slash See 1 
Separator 125 2 note 
Page number 127 4 Object See Max. 10 
Separator 131 2 neh 
Note: The start column for this data is variable. The Sepalalor oS gs 
title is centered between the left margin and the sepa- System name 103 8 
rator following the title. Separator 114 2 
Table A-29. First Line of Heading with Print Width 80 pale nls g 
Start Separator 121 2 
Data Column Length Time 123 8 
Title See Max. 55 Separator 131 2 
we Note: The library and object are formatted as 
Separator See 4 OBJLIB/OBJ with trailing blanks stripped from the 
note. OBJLIB and OBJ values. The OBJLIB/OBJ aggregate 
"Page" (with expansion) ea Nee is right-justified against the separator before the system 
name. 
note. 
Separator 73 2 
Page number 75 4 
Separator 79 2 


Note: The start column for this data is variable. 


A-144 Application Display Programming V4R1 


Table A-31. Second Line of Heading with Print Width 
80 


Start 
Data Column Length 
Product code 1 Max. 22 
Separator 23 Min. 3 
Library See Max. 10 
note 
Slash See 1 
note 
Object See Max. 10 
note 
Separator 47 4 
System name 51 8 
Separator 59 2 
Date 61 8 
Separator 69 2 
Time 71 8 
Separator 79 2 


Note: The library and object are formatted as 
OBJLIB/OBJ with trailing blanks stripped from the 
OBJLIB and OBJ values. The OBJLIB/OBJ aggregate 


is right-justified against the separator before the system 


name. 


PRTHEAD Tag 


Example: Print Title Line 


The following example has a title line for output 
with a width of 132 bytes. The title is from the 
print head panel or the first print panel. The page 
text and page number are provided by the UIM. 


Either the UIM or the application can provide the 
date and time. The application must use the 
PRTDATE and PRTTIME attributes on the PRTHEAD 
tag to specify a date and time. If the PRTDATE and 
PRTTIME attributes are not specified, the UIM uses 
the system date and time when the QUIOPNPA 
API or the QUIADDPA API is called. The date 
and time are formatted using the job attributes. 


This is an Example of a Print Title Line Page 1 


5738SS1 V2R1M0 900101 


QNETUSER/ EXAMPLE SYSTEMO1 05/25/90 11:09:04 
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PRTPNL Tag 


PRTPNL (Print Panel) 


>>—: PRTPNL—NAME=panel -name 


Lai theSdiateg=ventab leanne ee pplecnone 


Le tepavi 


" | 


80 | 
WIDTH= 132 


:EPRTPNL. >< 


A print panel (PRTPNL) tag contains tags to 
define one or more area definitions for a print 
panel. It requires a matching EPRTPNL tag. 


Other tags can be nested within the PRTPNL tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-32. Tags Allowed Between the PRTPNL and 
EPRTPNL Tags 


Tag Name Order Use Page 
DATA 1 P A-31 
(Data presenta- 

tion area) 

INFO 1 P A-68 
(Information area) 

LIST 1 P A-82 
(List area) 


Required Attribute 


NAME=panel-name 
The name of the print panel. For more infor- 
mation on the rules for naming, see “Name 
Syntax” on page A-4. 
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Optional Attributes 


TITLE=dialog-variable-name 
The name of a dialog variable containing the 
text for the panel title when the panel is 
printed. The dialog variable must be defined 
with a class that has a width of 55. The UIM 
trims trailing blanks from the string and 
centers the resulting text in the title line of the 
print panel. If this attribute is used, no title- 
text can be specified. 


TT=truth-table-name 
The name of a truth table that specifies what 
combinations of truth values may occur at run 
time when the panel is printed. 


The table specified on this tag may contain a 
subset of the conditions referred to by tags in 
the print panel. Only the truth value combina- 
tions specified in the table, augmented by 
worst-case assumptions for any truth values 
not specified in the table, are considered in 
evaluating whether or not the print panel defi- 
nition is valid. The table should not exclude 
any truth value combination that could occur 
when the print panel is printed. If a valid truth 
value combination is omitted, a panel group 
object may create without error and produce 
undesirable results when panels are printed. 


If this attribute is omitted, all combinations of 
truth values are considered possible. This 
causes the tag language compiler to make 
worst-case assumptions for all conditions in 
evaluating whether or not the print panel is 
valid. 


WIDTH=80 | 132 
Defines the width, in bytes, of the print panel. 
The default value is 80 bytes. 


Optional Text 


PRTPNL Tag 


title-text text (RT) tag, and cannot exceed 55 charac- 
The title used on this print panel. The text ters in length. The title-text is not allowed if 
must appear on the same or next line as the the TITLE attribute is specified on this tag. 


tag. The text can only contain the reverse 
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PRTTRAIL Tag 


PRTTRAIL (Print Trailer Message) 


p>>—:PRITRAIL. trailer-message-text 


>< 


The print trailer message (PRTTRAIL) tag is 
allowed only within the print head panel 
(PRTHEAD) tag, appearing immediately before the 
EPRTHEAD tag. The trailer message is printed at 
the end of the print listing. If no trailer is speci- 
fied, no default trailer is printed. 


Note: The trailer is only printed when the printer 
file is closed by using the option for a normal 
close on either the Close Application (QUICLOA) 
API or the Remove Application (QUIRMVPA) API. 
The trailer is not printed if the application is closed 
using the option for an abnormal close. 


Required Text 


trailer-message-text 
The text appearing at the end of the print 
listing. This text can be entered without 
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leading or trailing asterisks (*). The UIM adds 
asterisks before and after the text. 


The text can be a maximum of 106 bytes for 
WIDTH=132 and a maximum of 54 bytes for 
WIDTH=80, specified on a PRTHEAD tag. The 
text can contain only the reverse text (RT) tag. 


Example: Trailer Message 


This example shows what kind of text a print 
trailer message might have. 


UIM Source 


:prttrail.END OF LISTING 


PV Tag 


PV (Programming Variable) 


>< 


p>>—:PV.programming-variable:EPV. 


The programming variable (PV) tag identifies a 
programming variable. It requires a matching end 
tag. These tags are only allowed in information 
areas and help areas. It is frequently used within 
parameter lists. For more information on param- 
eter lists, see “PARML (Parameter List)” on 

page A-129. 


A programming variable can occur anywhere in 
the text to help explain the elements of program- 
ming syntax. 


The PV and EPV tag phrase must be specified on 
word boundaries. If the two characters imme- 


diately following the EPV tag are a punctuation 
mark and a blank, the UIM automatically extends 
the emphasis attribute to include the punctuation 
mark. This allows the punctuation mark and the 
text associated with it to be displayed using the 
same emphasis. 


Required Text 


programming-variable 
The programming variable. The text formats 
in highlight phrase 1 (HP1). 
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RT Tag 


RT (Reverse Text) 


pe—:RT.reverse-direction-text:ERT. 


>< 


The reverse text (RT) tag indicates that the 
enclosed text has an orientation opposite to the 
orientation of the panel group. This tag is ignored 
for panel groups with BIDI=NONE specified on 
the panel group (PNLGRP) tag. On a BIDI=RTL 
panel group, text in a left-to-right language is 
placed between the RT and ERT tags, while on a 
BIDI=LTR panel group, text in a right-to-left lan- 
guage is placed between the RT and ERT tags. 


With the import (IMPORT) tag, it is possible to 
combine help information from panel groups that 
have BIDI=RTL specified with help information 
from panel groups that have BIDI=LTR specified. 
This is not recommended, but when it does occur, 
the user needs to use the hot key sequence for 
the work station controller to flip the screen to 
read the help information with the opposite orien- 
tation. Any text within the RT and ERT tags is for- 
matted correctly for its panel group orientation. 
Therefore, when the RT tag is used for text that is 
imported into help information with the opposite 
orientation, the imported text is also readable 
when the screen is flipped. 


Unlike the highlight phrase tags, the RT tag is 
allowed within the text of most tags. The following 
tags allow an imbedded RT tag: 


LISTGRP List group 

LI List item 

LP List part 

MBARC Menu bar choice 
MENU Menu area 

MENUI Menu item 

NT Note 

OPTLINE Option line 

P Paragraph 

PC Paragraph continuation 
PD Parameter description 
PT Parameter term 
PRTHEAD Print head panel 
PRTPNL Print panel 
PRTTRAIL Print trailer message 
PDFLDC Pull-down field choice 
TOPINST Top instruction line 


The RT tag cannot be used within a figure (FIG), 
unformatted lines (LINES), or an example (XMP) 
tag. No tag is allowed between an RT tag and its 
matching ERT tag. 


Blanks found between an RT tag and its matching 
ERT tag are preserved. This includes the trailing 
blank at the end of each source line. Therefore, 
starting a source line with an ERT tag is not 
recommended. 


BOTINST Bottom instructions 
CIT Title citation 
CMDLINE Command line 

DATA Data area 
DATASLTC Data selection choices 
DATAGRP Data group 

DATAI Data item 

DD Definition 

DDHD Definition header 

DT Definition term 

DTHD Definition term header 
FIGCAP Figure caption text 

Hn Headings 

HPn Highlighted phrase 
INFO Information area 

KEYI Key list item 

LINK Hypertext link definition 
LIST List area 

LISTACT List action 
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Example 1: Left-to-Right 
Formatting on a Right-to-Left 
Panel 


This example illustrates left-to-right source for- 
matted and displayed on a right-to-left panel. 


UIM Source 


:P.For more information see the 

:CIT.:RT.IBM 0S/400 User Interface 
Manager Reference Manual:ERT.:ECIT. 
which you can find in your library. 


Results 


IBM 0S/400 User eht ees noitamrofni erom roF 


uoy hcihw Interface Manager Reference Manual 
-yrarbil ruoy ni dnif nac 


Example 2: Left-to-Right 
Formatting on a Left-to-Right 
Panel 


This example illustrates left-to-right source for- 
matted and displayed on a left-to-right panel. 


UIM Source 


RT Tag 


:P.This is an example of some 
:RT.PRETEND HEBREW TEXT:ERT. 
imbedded within some real 
English text. 


Results 


This is an example of some DNETERP 
TXET WERBEH imbedded within some 
real English text. 
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SL, LI Tags 


SL (Simple List) 


pe—:SL ‘ :LI.item-text | 


:ESL. >< 


Lcom pact— 


The simple list (SL) tag identifies a list of items. It 
requires a matching end tag. These tags are only 
allowed in information areas and help areas. 


Simple lists can occur anywhere in text and can 
be nested within other lists. 


Care should be taken when using the unformatted 
lines (LINES), figure (FIG), and example (XMP) 
tags within simple lists, because text that does not 
fit on one line wraps to column one of the next 
line. Lines and figures start at the current left 
margin, and examples are indented four spaces 
from the current left margin. The current left 
margin changes when nested lists are formatted. 
If there is help information containing the LINES, 
FIG, or XMP tags imbedded at various locations, 
including within lists, it may not look the same 
each time and can cause undesirable results. 


Simple lists are formatted as hanging, indented 
lists, with no item identifier. 


Other tags can be nested within the SL tag. 

These tags are listed in the following table. The 
table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-33. Tags Allowed Between the SL and ESL 
Tags 


Tag Name Order Use Page 
FIG 1 B A-59 
(Figure) 
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Table A-33. Tags Allowed Between the SL and ESL 
Tags 


Tag Name Order Use Page 
LINES 1 B A-77 
(Unformatted 

lines) 

XMP 1 B A-171 
(Example) 

NT 1 B A-117 
(Note) 

P 1 B A-121 
(Paragraph) 

PC 1 B A-131 
(Paragraph con- 

tinuation) 

LP 1 B A-107 
(List part) 

OL 1 B A-118 
(Ordered list) 

SL 1 B A-152 
(Simple list) 

UL 1 B A-164 
(Unordered list) 

PARML 1 B A-129 
(Parameter list) 

DL 1 B A-57 


(Definition list) 


Optional Attribute 


COMPACT 
The list is formatted with no blank line 
between the items. 


Required Tag 


:LI.item-text 
The text for the list item. The text is indented 
four spaces from the current margin. 


Example: Simple Lists 


This example uses two simple lists, one imbedded 
within the other. The second simple list uses the 
COMPACT attribute. 


UIM Source 


Some normal text... 
2s]. 

:1i.First item 

:sl compact. 
:1li.First item 
:1i.Second item 
ses]. 

:1i.Second item 
ses]. 


SL, LI Tags 


Results 


Some normal text... 
First item 


First item 
Second item 


Second item 
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TEXT tag 


TEXT (Text Area) 


> 


p>>—: TEXT—VAR=dialog-variable-name—USREXIT='CALL program-reference' > 


L_RoW=dialog- variable-name Cotedigidgivaniablesnane 


>< 


The text area (TEXT) tag defines a text area ina 
panel to be formatted by the application. Only 
one TEXT tag can be specified in each panel. 
Menu bars and command lines are allowed, 
however, no other areas can be defined in the 
panel. 


The width of this area is determined by the WIDTH 
attribute of the PANEL tag which this area is 
defined in. 


The depth of this area is the depth of the panel. 
The depth of the panel is determined by the DEPTH 
attribute of the PANEL tag which this area is 
defined in. The DEPTH value is reduced by any 
lines used for other parts of the panel such as a 
menu bar lines, the panel title line, the command 
lines, the function key line(s), and the message 
line(s). See the PANEL tag for a description of 
these dimensions. 


The data passed to the UIM to be displayed in this 
area is described in the “Text Data” on 
page A-155 section below. 


If the Help key is pressed while the cursor is in 
the text area extended help for the panel is dis- 
played. 


Required Attribute 


VAR=dialog-variable-name 

The name of the dialog variable containing the 
data, or a pointer to the data, for the text area. 
Define the dialog variable using a class defi- 
nition (CLASS) tag with basetype of CHAR X 
or PTR. The CHRID=PNLGRP attribute is not 
allowed on the class definition for this dialog 
variable. 


The data in the dialog variable is viewed by 
the UIM as a d by warray of characters, 
where dis the depth and wis the width of the 
text area. Each row of the array is displayed 
as one line of the text area. 
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If the dialog-variable-name has a BASETYPE of 
CHAR on its CLASS tag, this dialog variable 
contains the data for the text area. 


If the dialog-variable-name has a BASETYPE of 
PTR on its CLASS tag, this dialog variable 
contains a pointer to the data for the text area. 
The data pointed to by this pointer is viewed 
by UIM the same as for a dialog variable with 
a BASETYPE of CHAR. Any exception the UIM 
receives while accessing this data will result in 
an escape message sent to the calling 
program. 


The dialog variable can be declared as any 
size. If there is not enough data to fill the text 
area the remainder of the text area will be 
blank. If there is more than enough data to fill 
the text area only the data needed to fill the 
text area will be used. 


You can use the exit program for the text 
area, specified on the USREXIT attribute of this 
tag, to update this dialog variable each time 
the panel is displayed. The UIM uses the 
value of the dialog variable to work with the 
data for the text area as described in “Text 
Data” on page A-155. The value of the dialog 
variable depends on the BASETYPE attribute on 
the CLASS tag of the dialog variable. 


The size of the text area can vary depending 
on the number of rows taken up by the func- 
tion keys. This is important to remember when 
coding for multiple languages or conditioning 
function keys with the condition (COND) tag. 


USREXIT=' CALL program-reference' 
The exit program called to update the value of 
the dialog variable on the VAR attribute each 
time the panel is displayed. 


This area will be considered scrollable by the 
UIM. If the user presses a key assigned to a 
scrolling dialog command and the text area 
should be scrolled (as opposed to other 
scrollable areas on the panel) the UIM will call 
the user exit program. On return the UIM will 


redisplay the panel. For a description of the 
user exit program structure passed by the 
UIM, see the System API Reference. 


A general panel exit program should be used 
to diagnose if the user has scrolled too far. If 
the user has scrolled too far the general panel 
exit should send an appropriate message fol- 
lowed by the special message to cancel the 
determined action. For a description of the 
general panel exit program structure passed 
by the UIM, see the System API Reference. 
this is done the message telling the user he 
has scrolled to far will only be seen once. If 
the text area exit sends the message it may 
be displayed on the screen longer than 
desired. 


f 


For a description of the CALL dialog 
command, see Appendix B, “UIM Dialog 
Commands’ on page B-1. 


Optional Attributes 


ROW2=dialog-variable-name 
The row of the cursor. Define the dialog vari- 
able using a class definition (CLASS) tag with 
BASETYPE of BIN(31). 


The dialog variables for the row and column 
can be set by the application before calling 
the UIM to set the location of the cursor within 
the text area. The first character of the first 
row in the text area would be row 1 and 
column 1. A value of zero in either of the 
dialog variables tells the UIM to use default 
cursor positioning. 


When the UIM returns to the application, it will 
set these dialog variables to the row and 
column where the cursor was positioned in the 
text area when the user exited the panel. If 
the cursor was not within the text area when 


TEXT tag 


the user exited the panel the row and column 
dialog variables will both be zero. 


COL=dialog-variable-name 
The same as ROW except this is the column of 
the cursor. 


Cursor positioning 


The cursor position in a panel with a text area 
depends on many things. The following is a prior- 
itized list for where the cursor will be positioned. 
The first item that holds true will position the 
cursor. 


1. If the ROW and COL attributes are used on the 
TEXT tag and the value of the dialog variables 
are valid when the panel is displayed, the 
cursor is positioned at that row and column. 


2. If the panel has a command line the cursor is 
positioned at the command line. 


3. If the panel has a menu bar the cursor is posi- 
tioned at the first menu bar choice. 


4. If the text area has tabable highlighting 
classes the cursor is positioned at the first 
one. 


5. If none of the above position the cursor the 
cursor will be positioned at the upper left 
corner of the panel or pop-up window. 


Text Data 


Any character within the data can be a selection 
character for a highlighting class. Only output 
data is allowed in a text area; no input fields are 
allowed. The highlighting of the text applies to the 
characters following the class selection character 
up to another class selection character or the end 
of the area, whichever occurs first. 


The following table describes the selection characters for highlighting that are recognized by the UIM: 
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TEXT tag 


Hexadecimal Value Decimal Value Color Display Monochrome Display 
X’01’ 01 Blue Normal 
X’02’ 02 Green Normal 
X’03’ 03 Turquoise* Normal 
x’04’ 04 Red High Intensity 
X’05’ 05 Pink Normal 
X’06’ 06 Yellow* High intensity 
X’07’ 07 White High intensity 
x11" 7 
me 23 White reverse image 
x19 25 Blue underscore Normal underscore 
X1A’ 26 Green underscore Normal underscore 
X’'1B’ 27 Turquoise underscore * Normal underscore 
X10’ 28 Red underscore High intensity underscore 
X’1D’ 29 Pink underscore Normal underscore 
X'1E’ 30 Yellow underscore * High intensity underscore 
X1F’ 31 White underscore High intensity underscore 
xX’21’ 33 Blue tab Normal tab 
X’22’ 34 Green tab Normal tab 
X23’ 35 Turquoise tab * Normal tab 
X24 36 Red tab High intensity tab 
25° 37 Pink tab Normal tab 
X26’ 38 Yellow tab * High intensity tab 
X27’ 39 White tab High intensity tab 
X'34 52 
x35) 53 
x'36' 4 | Yellow reverse image tab | 
x37" 55 
X'39’ 57 Blue underscore tab Normal underscore tab 
X'3A’ 58 Green underscore tab Normal underscore tab 
X’3B’ 59 Turquoise underscore tab * Normal underscore tab 
X’3C’ 60 Red underscore tab High intensity underscore tab 
X’3D’ 61 Pink underscore tab Normal underscore tab 
X’3E’ 62 Yellow underscore tab * High intensity underscore tab 
X’3F’ 63 White underscore tab High intensity underscore tab 


* On some displays this highlighting class will display column separators 
and the blank character will look like a small box on the screen. 


Figure A-1. Highlighting Classes Allowed in TEXT Area 
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RV3W081-0 


The UIM replaces each class selection character 
with the appropriate display attributes for the 
class. Other character values in the ranges X'10' 
through X'3F', as well as X'FF', are converted 
to X'1F', appearing as a reverse image box on 
the screen. Characters X'00' (null), X'OE' 
(shift-out for double-byte), X'OF' (shift-in for 
double-byte), and X'40' through X'FE' (normal, 
displayable characters), are passed unchanged to 
the screen. 


For best appearance you should not place text in 
the first and last column of a panel. This also 
allows you to highlight the first word in any row 
easily. 


If you are trying to create a tabable phrase of a 
particular color do not use blanks between the 
words of the phrase. You should use the non- 
tabable highlighting class of the same color. This 
will give you the most effective display on all work 
stations. 


When a panel is displayed with tabable high- 
lighting classes in the text area the cursor is not 
automatically located on the first one. If you want 
this to happen you must use the ROW and COL 
attributes of this tag to set the location of the 
cursor. 


If one or more tabable highlight classes are placed 
next to each other in the data only the last one will 
allow tabbing. The others will be ignored. The 
maximum number of tabable fields is 240. It may 
be less if there are other input capable or tabable 
fields on the display such as the command line or 
menu bar choices. 


If any highlighting class is placed in the last 
column of the last row in a full screen panel or in 
the last column of any row in a pop-up window, it 
will be ignored. 


TEXT tag 


For pop-up windows highlighting classes never 
continue on the next line. You must use another 
highlighting class if you want it to continue. 


If a panel smaller than the device is displayed 
without adding a pop-up window first, highlighting 
classes continue into the blank space to the right 
of the panel on the screen. To turn off these high- 
lighting classes use other highlighting classes at 
the end of each row that look like blank space. 


No character set and code page conversion is 
done on the text area data. The application should 
provide the data in the correct character set and 
code page for the device. 


When the UIM calls the exit program to format the 
text area, it passes a value which identifies the 
BIDI attribute on the panel group (PNLGRP) tag 
and the code page number of the display device. 


If the NBRSHAPE and SYMSWAP attributes are used on 
the CLASS tag for the text area dialog variable 
they will be ignored. 


If DBCS data is used the application is fully 
responsible to make sure it displays properly. An 
error will occur if you attempt to display half of a 
DBCS character or if one of the IGC shift charac- 
ters (X'OE', X'0OF') is missing. 


Example: Text area 


[ | 
Computer bug 


F3=Exit F12=Cancel 
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TI Tag 


TI (Translation List Item) 


pe—:TI 


LvaLuE= ‘internal-value eis atepiaveavaries 


>< 


The translation list item (Tl) tag specifies a list 
item in a translation list. This tag must occur 
between translation list (TL) and ETL tags. The 
item is translated on output to the panel and on 
input to the variable pool. 


Optional Attribute 


VALUE=" internal-value' . 
The internal value for the dialog variable in the 
variable pool. This internal value is not 
subject to validity checks defined by the 
validity checking (CHECK) tag for this class. 
If the same internal value is specified more 
than once in the list, the first item in the list is 
chosen for translation on output. 


If the BASETYPE of this class is BIN, as speci- 
fied on the class definition (CLASS) tag, the 
value may be specified in either integer or 
hexadecimal notation. If the BASETYPE speci- 
fied on the CLASS tag is CHAR, IGC, DATE, 
TIME, NAME, or OBJNAME, the value may be 
specified in either string or hexadecimal string 
notation. Strings are implicitly padded on the 
right with blanks, but no implicit padding is 
done for hexadecimal notation. 
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If the internal value is specified in string or 
hexadecimal notation, the value must be 
enclosed in quotation marks in addition to 
apostrophes. For example, an internal value 
of *YES must be specified as VALUE=""YES". 


Omitting the VALUE attribute leaves the internal 
dialog variable value unchanged when the 
user enters the displayed-value specified as 
tag content after the period. A TI tag of this 
type has no effect on the way internal values 
are presented to the user for display. 


Optional Text 
displayed-value 


The value appearing on the panel or entered 
by the user. The comparisons done by the 
UIM to determine what internal value to use 
for an external value specified by the user 
may be changed by the CASE and BLANKS attri- 
butes of the CLASS tag. If the same external 
value appears more than once in the list, the 
first item is used for translation on entry. If no 
value is specified, a display value of blanks is 
used. 


TL Tag 


TL (Translation List) 


pp—:TL | 


CASE= | MIXED 


> 


UPPER | | MSGID-message- identifier! 


DaisGrstgualipiedlmessugexfiiesname = 


:ETL >< 


The translation list (TL) tag allows the specification 
of a translation list for a class, shielding the vari- 
able pool from the values actually entered on the 
display. Values with a BASETYPE of CHAR, IGC, 
DATE, TIME, NAME, OBJNAME, or that are 
numeric on the class definition (CLASS) tag can 
have a translation list. Only one translation list is 
allowed for each class. Translation occurs before 
any validity checks are performed. 


Other tags can be nested within the TL and ETL 
tags. These tags are listed in the following table. 
This table defines the order in which the tags must 
appear and specifies on which page more infor- 
mation can be found for each tag. 


Table A-34. Tag Allowed Between the TL and ETL 
Tags 


Tag Name Order Page 


Tl 1 A-158 
(Translation list item) 


Optional Attributes 


CASE=UPPER | MIXED 
UPPER indicates that lowercase characters (a 
through z) in an input field value are con- 
verted to uppercase characters (A through Z) 
before comparison to the external value for 
each translation list item. This conversion to 
uppercase occurs after any conversion for the 
CASE attribute on the CLASS tag, but has no 
effect on the value assigned to the dialog vari- 
able or list entry if no matching translation list 
item is found. It also does not change the 
external display value specified on each trans- 
lation list item (Tl) tag; the text on the TI tag 
must be specified in uppercase to get a 
match. 


MIXED indicates that an input value is com- 
pared as it is entered with the external value 
specified on each TI tag. 


MSGID=message-identifier 

The message identifier of the message sent if 
the translation fails because the user entered 
a value not specified in the list. If this attri- 
bute is not specified, the UIM assumes that 
the entered value is valid as it is entered and 
passes the value on to validity checking for 
the class. 


MSGF=' qualified-message-file-name' 
The message file containing the message sent 
for this error if the translation fails. If the 
DFTMSGF attribute is not specified on the panel 
group (PNLGRP) tag, this attribute must be 
specified if the MSGID attribute is specified on 
this tag. 


Examples: Translation List 


This example shows how a translation list is 
defined. 


UIM Source 


:t]_ msgid=MMMQ001 msgf='*LIBL/QCPFMSG'. 
:ti value=1.Blue 

:ti value=1.BLUE 

:ti value=2.Red 

:ti value=2.RED 

:ti value=3.Green 

:ti value=3.GREEN 

:ti value=4.Turquoise 

:ti value=4. TURQUOISE 

setl. 


On entry, Blue, due to the default CASE=UPPER 
and the uppercase version of the translation item, 
is mapped to the value 1. On output, 1 is mapped 
to the value Blue, which is mixed case, because 
the first matching translation list item is always 
used. Notice that because the integer notation is 
used for the value, the BASETYPE on the CLASS 
tag that this translation list applies to must be 
numeric. 
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TL Tag 


This is an example of a class definition and a UIM Source 
translation list for a dialogue variable that allows a 
valid OS/400 library name (*LIBL, *CURLIB, or 
blanks). stil 

:ti value='"*LIBL"'.*LIBL 

:ti value='"*CURLIB"'.*CURLIB 

:ti value='"" nan 


:class name=objlibc 
basetype='objname 10'. 


seclass. 
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TOPINST Tag 


TOPINST (Top Instruction) 


p>>—: TOPINST 
iNsTedteteawvariabtecntne! 


>< 
Ld foteueransreree 


The top instruction (TOPINST) tag of an area 
specifies the top instruction lines. This tag is valid 
for all areas, but is allowed only for display panels. 
It appears immediately after the introducing tag for 
the area. 


Multiple top instruction tags may be used to 
present multiple lines of instructions if the 
TOPINST tag contains instruction-text. |f multiple 
TOPINST tags are coded, no blank lines appear 
between the text on different tags. Only one top 
instruction tag is allowed per area if an INST attri- 
bute variable is used for this tag. 


For menus, a blank line is always left between the 
body and the instruction lines area. For more 
information about how instruction lines are for- 
matted with respect to the body of certain areas, 
see the BODYSEP attribute in “DATA (Data Presen- 
tation Area)” on page A-31. 


If no TOPINST tag is specified for an area, no text 
is used for the instruction line and the line is not 
allocated in the area. 


Optional Attribute 


INST=dialog-variable-name 
The name of a dialog variable containing the 
top instruction text displayed. The dialog vari- 
able must be defined with a width less than or 
equal to the width specified on the panel tag 


minus two. If this attribute is used, no 
instruction-text can be specified for this tag. 


Dialog variables must be defined with a 
BASETYPE of CHAR, IGC, or BIN on the class 
definition (CLASS) tag. 


The error state of the dialog variable is not 
used for determining the highlighting of the 
text. 


Special formatting for IGC. The abbrevi- 
ation IGC is used in commands and keywords 
to represent double-byte character set (DBCS) 
functions. When a dialog variable with a 
BASETYPE of IGC is specified on the CLASS 
tag, the UIM does special formatting. If the 
variable value begins with a shift-out character 
(X'OE'), the UIM shifts the value 1 byte to the 
left to preserve vertical alignment with other 
lines. 


Optional Text 


instruction-text 
The text appearing as top instructions for the 
area. The text is an implied paragraph. 
When the display is formatted, any text that 
does not fit onto one display line is formatted 
onto additional lines as necessary and 
indented two positions. The text can be a 
maximum of 255 characters, and can only 
contain the reverse text (RT) tag. The instruc- 
tion text is required unless the INST attribute is 
specified on this tag. 
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TT Tag 


TT (Truth Table) 


>>—: TT—NAME=truth-table-name—CONDS='condition-name-list'—.—:ETT. >< 


The truth table (TT) tag begins the definition of a 
truth table used by the compiler when processing 
panel definitions. The TT tag must occur in the 
prolog section of the panel group after the condi- 
tion definition (COND) tags and before any menu 
bar (MBAR) tags. You should use a truth table to 
assert to the UIM which conditions are mutually 
exclusive. 


During compilation of a panel group, a panel is 
formatted once for each row of a truth table. 
Using the truth value for each condition, the com- 
piler checks if the panel definition is valid. Ifa 
panel element is conditioned using the COND attri- 
bute on this tag, and if that condition is not men- 
tioned in the truth table, it is assumed to have a 
true value by the compiler. 


The name of a truth table must be specified on 
the TT attribute of the display panel (PANEL), print 
panel (PRTPNL), or print head panel (PRTHEAD) 
tag for the compiler to use the truth table for panel 
verification. 


After the compile, if the truth table is wrong and 
the conditioning causes more panel elements to 
be active in an area than can be displayed, only 
the elements that fit are displayed, and no excep- 
tion is reported. 


Other tags can be nested within the TT tag. 
These tags are listed in the following table. This 
table defines the order in which the tags must 
appear and specifies on which page more infor- 
mation can be found for each tag. 
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Table A-35. Tag Allowed Between the TT and ETT 
Tags 


Tag Name Order Page 


TTROW 1 A-163 
(Truth table row) 


Required Attributes 


NAME=' truth-table-name' 
The name of the truth table. For more infor- 
mation on the rules for naming, see “Name 
Syntax” on page A-4. This name is referred 
to by all panels which use this truth table for 
compile-time checking. This name must be 
unique within the panel group. 


CONDS=' condition-name-list' . 
A list of condition names separated by blanks. 
Each condition in the list must have been pre- 
viously defined with the COND tag. The rows 
of the truth table are defined with the truth 
table row (TTROW) tag. Each item in the 
VALUES attribute of the TTROW tag corre- 
sponds positionally with the condition specified 
in this attribute. A maximum of 50 condition 
names can be specified. 


Example: Truth Table 


If conditions A, B, and C are known to be mutually 
exclusive on panel X, this example would illustrate 
how to assert this to the compiler. 


UIM Source 

:tt name=ttl conds='A BC'. 
:ttrow values='1 0 Q'. 
:ttrow values='0 1 Q'. 
:ttrow values='0 @ 1'. 
sett. 


TTROW Tag 


TTROW (Truth Table Row) 


>>—: TTROW—VALUES='condition-value-list' 


>< 


The truth table row (TTROW) tag defines a row in 
a truth table used by the compiler when pro- 
cessing panel definitions. The TTROW tag must 
occur between the truth table (TT) and ETT tags 
in the prolog section of the panel group. 


During compilation of a panel group, a panel is 
formatted once for each row of a truth table, and 
the truth value for each condition is used to check 
if the panel definition is valid. A truth table can 
describe which of the conditions that control the 
formatting of a panel are mutually exclusive. Ifa 
condition is used within the panel definition and is 
not mentioned in the truth table, it is assumed to 
be true for the purposes of compile time checking; 
this is the same as specifying an asterisk (*) in the 
VALUES attribute on this tag. 


Required Attribute 


VALUES=' condition-value-list'. 
The value of each condition used by the com- 
piler to check the panel definition. Each item 
in the VALUES attribute of the TTROW tag cor- 
responds positionally with the condition speci- 
fied in this attribute. The following values can 
be used for the condition: 


0 The condition is false. 

1 The condition is true 

* No truth value is specified. The compiler 
assumes the value is true for a worst 
case. 


The items in the list of condition values are 
separated by blanks. The number of items in 
the list must equal the number of items in the 
CONDS attribute of the TT tag. 
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UL, LI Tags 


UL (Unordered List) 


p>—:UL ‘ :LI.item-text 


Lcom pact— 


:EUL. >< 


The unordered list (UL) tag identifies an unordered 
list of items. The UL tag requires a matching end 
tag. These tags are only allowed in information 
areas and help areas. 


Unordered lists can occur anywhere in text and 
can be nested within other lists. 


Note: Care should be taken when using the 
unformatted lines (LINES), figure (FIG), and 
example (XMP) tags within unordered lists, 
because text that does not fit on one line wraps to 
column one of the next line. Lines and figures 
start at the current left margin and examples are 
indented four spaces from the current left margin. 
The current left margin changes when nested lists 
are formatted. If there is help information con- 
taining the LINES, FIG, or XMP tag imbedded at 
various locations, including within lists, it may not 
look the same each time and can cause undesir- 
able results. 


Unordered lists are formatted as hanging, 
indented lists, with the item identifier at the current 
left margin. There are three levels of item identi- 
fiers for nested, unordered lists: 


¢ Bullets (lowercase letter o) 
¢ Hyphens (-) 
e Dashes (--). 


These levels are repeated for more than three 
levels of nested, unordered lists. 


Other tags can be nested within the UL tag. 
These tags are listed in the following table. The 
table defines the order in which the tags must 
appear, indicates which tags can be used in 
display panels only, print panels only, or both 
(specified by a D, P, or B, respectively), and spec- 
ifies on which page more information can be found 
for each tag. 


When more than one tag is listed with the same 
order number, all tags of that number can be 
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mixed in any order. However, a tag with a higher 
order number cannot precede a tag with a lower 
order number. For example, a tag with an order 
number of three cannot precede a tag with an 
order number of one or two. 


Table A-36. Tags Allowed Between the UL and EUL 
Tags 


Tag Name Order Use Page 
FIG 1 B A-59 
(Figure) 

LINES 1 B A-77 
(Unformatted 

lines) 

XMP 1 B A-171 
(Example) 

NT 1 B A-117 
(Note) 

P 1 B A-121 
(Paragraph) 

PC 1 B A-131 
(Paragraph con- 

tinuation) 

LP 1 B A-107 
(List part) 

OL 1 B A-118 
(Ordered list) 

SL 1 B A-152 
(Simple list) 

UL 1 B A-164 
(Unordered list) 

PARML 1 B A-129 
(Parameter list) 

DL 1 B A-57 


(Definition list) 


Optional Attribute 


COMPACT 
The list is formatted without a blank line 
between the items. 


Required Tag 


:LI.item-text 
The text for the list item. This text is pre- 
ceded by the item identifier; the text is 
indented four spaces from the current margin. 


Example: Unordered Lists 
This example uses two unordered lists, one 


imbedded within the other. The second unordered 
list uses the COMPACT attribute. 


UIM Source 


UL, LI Tags 


Some normal text... 

sul. 

:11.First item (bullet) 
:ul compact. 

:li.First item (hyphen) 
:1i.Second item (hyphen) 
seul. 

:11.Second item (bullet) 
seul. 


Results 


Some normal text... 
e First item (bullet) 


— First item (hyphen) 
— Second item (hyphen) 


e Second item (bullet) 
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VAR Tag 


VAR (Variable Definition) 


>>—: VAR—NAME=variable-name 


Leides: Giasesiames! 


> 
LeRRVAR=error-s sabieeventab tounge. 


>< 


The variable definition (VAR) tag declares a dialog 
variable in the panel group. The VAR tag does 
not allow nested tags and must be placed after 
the last class definition (CLASS) tag and before 
the first variable record definition (VARRCD) tag. 


A value for each dialog variable exists in the vari- 
able pool for an application opened using this 
panel group. The dialog variables communicate 
values to and from panels when the panels are 
presented to the user. Dialog variable values are 
set and retrieved using the UIM application pro- 
gramming interfaces (APIs). 


The VAR tag defines all Z-variables, as well as 
other dialog variables used by an application. 
Only variables defined by a VAR tag in the panel 
group source are available in an open application. 


Required Attribute 


NAME=variable-name 
The name of a dialog variable. This name 
must be unique within the panel group. For 
more information on the rules for naming, see 
“Name Syntax” on page A-4. 


Optional Attributes 


CLASS=class-name 
The name of the class to which this variable 
belongs. The class must have been previ- 
ously defined in the panel group. 


The class definition for all Z-variables is deter- 
mined by the UIM, so this attribute cannot be 
specified on the VAR tag for a Z-variable. A 
class must be specified for other variables 
declared in the panel group. 


ERRVAR=error-status-variable-name 
The name of a dialog variable, automatically 
defined by the UIM with a BASETYPE of 
CHAR 1 on the CLASS tag. The error status 
variable must not be defined by another VAR 
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tag. This name must also be unique within 
the panel group. 


This dialog variable contains the error status 
of the variable defined by this tag. This attri- 
bute is used with the Put Dialog Variable 
(QUIPUTV) API and the Get Dialog Variable 
(QUIGETV) API. 


During the QUIPUTV API, the current value of 
the error variable determines the error status. 
A value of 1 (X'F1') indicates that the dialog 
variable specified on the NAME attribute on this 
tag is in error. A value other than 1 (X'F1') 
indicates that the dialog variable is not in 
error. If the error status variable is updated 
during the same QUIPUTV API request as its 
associated dialog variable, the new value of 
the error status variable is used. 


During the QUIGETV API for either the NAME 
dialog variable or the ERRVAR dialog vari- 
able, the value of the error status variable is 
set to 1 (X'F1') if the dialog variable specified 
on the NAME attribute of this tag is in error. 
Otherwise, the value of the error status vari- 
able is set to zero (X'FO'). 


Note: Simply updating the ERRVAR dialog 
variable does not set the error state of the 
dialog variable specified in the VAR attribute of 
this tag. The VAR dialog variable must be 
updated using the QUIPUTV API to change its 
error state. 


The error dialog variable cannot be referred to 
any place in the panel group source where 
dialog variables can normally be specified. 


Dialog Variables Defined by UIM 


The UIM defines a set of dialog variables that can 
be automatically available in the variable pool for 
every open application. The variables must be 
defined using the variable definition (VAR) tag in 
order to be available in the variable pool. These 
variables can be referenced by user programs 


(see the QUIGETV API) and in panel definitions, 
and some can be modified by user programs (see 
the QUIPUTV API) to control UIM processing 
functions. Dialog variables are not allowed for 
input fields on any panel. 


All dialog variables defined by the UIM have 
names that begin with the letter Z. If you define a 
dialog variable for your application with the same 
name as a UIM dialog variable, you receive a 
warning message. The message states that you 
do not have access to the UIM dialog variable with 
the same name. However, you are allowed to use 
the dialog variable that you defined. The following 
is a description of all UIM-defined dialog variables: 


ZCANCEL Indicates whether the CANCEL func- 
tion is requested and is set as 
follows: 


0 The CANCEL function was not 
requested. 

1. The CANCEL function is 
requested. 


This Z-variable can be changed by 
the calling (application) program using 
the QUIPUTV API. Changing this 
dialog variable results in changing the 
job's cancel flag. For more informa- 
tion on the cancel flag, see “Folding 
Up a List Panel’ on page 17-26. 


ZDBCS Indicates whether the job is currently 


in DBCS mode, and is set as follows: 


0 The job is not in DBCS mode. 
1 The job is in DBCS mode. 


Indicates the maximum size of the 
display that the device is capable of 
displaying and is set as follows: 


ZDSPSIZ 


*DS3 The largest size panel the 
device can display is 24 x 80. 

*DS4 The largest size panel the 
device can display is 27 x 132. 
This device can also display 
panels of size 24 x 80. 


ZEXIT Indicates whether the EXIT function 


was requested and is set as follows: 


Q The EXIT function is not 
requested. 
1 The EXIT function is requested. 


VAR Tag 


This Z-variable can be changed by 
the calling (application) program using 
the Put Dialog Variable API service. 
Changing this dialog variable results 
in changing the job's exit flag. For 
more information on the job's exit 
flag, see “Folding Up Multiple Panels 
When EXIT Is Requested” on 

page 17-24. 


ZJOB Simple name of the current job (the 


first qualifier of the job name). 


ZJOBNBR Job number of the current job (the 
last qualifier of the job name). 


ZLMTCPB Indicates the limits to which the user 
controls the initial program, initial 
menu, current library, and Attention 
key handling program values and is 
set as follows: 


*NO 
*PARTIAL 
*YES 


Name of the menu object currently 
displayed by the UIM. This dialog 
variable can be used only in defi- 
nitions of *MENU objects. 


ZMENU 


ZMNULIB_ The name of the library that contains 
the menu object currently displayed 

by the UIM. This dialog variable can 
be used only in definitions of *MENU 


objects. 


ZSYSNAM Current system name retrieved from 
the SYSNAM network attribute. 


ZUSER User profile name for the current job 
(which is also the middle qualifier of 
the job name). 

Z36ENV Indicates whether the job is currently 


running in the System/36 environment 
and is set as follows: 


0 The job is not running in the 
System/36 environment. 

1 The job is running in the 
System/36 environment. 


For a description of the characteristics (including 
external display form) for the base type of each 
Z-variable, see “CLASS (Class Definition)” on 
page A-14. 
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VAR Tag 


Table A-37. Attributes of UIM-Defined Variables (Z-Variables) 


Program 

Base Modifi- 
Name Type Length able Description 
ZCANCEL CHAR 1 Yes Indicates whether the CANCEL function is required 
ZDBCS CHAR 1 No Indicates whether the job is in DBCS mode 
ZDSPSIZ CHAR 4 No Indicates the maximum size of display 
ZEXIT CHAR 1 Yes Indicates whether the EXIT function is requested 
ZJOB OBJNAME 10 No Job name of the current job (first qualifier) 
ZJOBNBR CHAR 6 No Job number of the current job 
ZLMTCPB CHAR 10 No Limits the capabilities the user has 
ZMENU OBJNAME 10 No Name of the menu object 
ZMNULIB OBJNAME 10 No Name of the library containing the menu object 
ZSYSNAM CHAR 8 No Current system name 
ZUSER OBJNAME 10 No User profile name 
Z36ENV CHAR 1 No Indicates if running in the System/36 environment 
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VARRCD Tag 


VARRCD (Variable Record Definition) 


> 


>>—: VARRCD—NAME=variable-record-name—VARS='variable-list' > 


Loput= 'variable-list il Loget= 'variable-list i] 


>< 


The variable record definition (VARRCD) tag does 
not allow nested tags, and must be placed after 
the last variable definition (VAR) tag and before 
the first list definition (LISTDEF) tag. 


When data is passed between a calling program 
and the variable pool, a variable buffer is used. 
The variable buffer contains values for one or 
more dialog variables. A VARRCD tag defines 
which dialog variables are in the variable buffer as 
well as the sequence the variables appear in the 
variable buffer. 


The VARRCD tag must be used to define a vari- 
able record definition for use with the Get Dialog 
Variable (QUIGETV) API and the Put Dialog Vari- 
able (QUIPUTV) API requests. Only variables 
defined by a VAR tag in the panel group source 
may appear in the variable record definition. 


Required Attributes 


NAME=variable-record-name 
The name of a variable record definition. This 
name must be unique within the panel group. 
For more information on the rules for naming, 
see “Name Syntax” on page A-4. 


VARS=' variable-list' 
A list of up to 256 dialog variables which 
make up the variable record. All dialog vari- 
ables in this variable list must be previously 
defined using the VAR tag. The dialog vari- 
able names in the list are separated by one or 
more blanks. 


The order in which the variable names appear 
in the variable list is the order the variable 
values must appear in the variable buffer of 
the calling program when the QUIPUTV and 
QUIGETV APIs are called. 


The variables must appear contiguously in the 
variable buffer for the calling program. The 


UIM makes no boundary alignment adjust- 
ments when calculating the offsets to vari- 
ables within the buffer. 


If any read-only Z-variables are listed in the 
VARS attribute of this tag, they must also 
appear in the NOPUT attribute of this tag. 


Optional Attributes 


NOPUTS=' variable-list' 
A list of up to 256 variables which should not 
be processed when the QUIPUTV API is 
requested. All variables in this variable list 
must appear in the variable list specified on 
the VARS attribute of this tag. The variable 
names in the list are separated by blanks. 


Using this attribute, you can specify that only 
a subset of the variables in the variable buffer 
should be copied to the variable pool during 
the QUIPUTV API. 


If this attribute is not specified, all variables 
specified on the VARS attribute of this tag are 
copied from the variable buffer to the variable 
pool during the QUIPUTV API. 


NOGET=' variable-list' 
A list of up to 256 variables which should not 
be processed when the QUIGETV API is 
requested. All variables in this variable list 
must appear in the variable list specified on 
the VARS attribute of this tag. The variable 
names in the list are separated by blanks. 


Using this attribute, you can specify that only 
a subset of the variables in the variable buffer 
should be copied from the variable pool during 
the QUIGETV API. 


If this attribute is not specified, all variables 
specified on the VARS attribute of this tag are 
copied from the variable pool to the variable 
buffer during the QUIGETV API. 
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XH1 through XH4 Tags 


XH1 through XH4 (Extended Help Headings) 


>> :XH1.——extended-help-heading-text 
:XH2. 
:XH3. 
>XH4. 


. 


>< 


The extended help heading (XH1-XHA4) tag identi- 
fies the heading used over contextual help when it 
is displayed as part of an extended panel help, 
including help for index search topics. This tag 
must appear within a help module (HELP) tag and 
EHELP boundary and is not allowed on the infor- 
mation (INFO) tag. The text associated with this 
tag is used as the heading text. 


This tag allows headings to appear with help infor- 
mation, based on whether the text is displayed for 
extended panel help or for contextual help. The 
text from XHn tags always appears in extended 
panel help. The text also appears in contextual 
help if any tag containing help information pre- 
cedes the XHn tag, or the contextual help is dis- 
played in a full screen and no help panel title is 
specified on the HELP tag. 


In all cases of contextual help, with the exception 

of the two previously mentioned, the text from the 
XHn tag does not appear when the XHn tag is the 
first tag used for contextual help. 


Required Text 


extended-help-heading-text 
The text associated with this tag is used as a 
heading when the help item is used in 
extended panel help. The text must be on the 
same or next line as the period ending the 
tag. 


Formatting Rules 


Headings have one blank line formatted before 
and after them. The heading tag generates a 
blank line before the heading, and the tag fol- 
lowing the heading generates the space after the 
heading. 


Specific formatting rules follow: 
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XH1 Centers, underscores and highlights text 
(HP3). This tag causes a page eject when 
it appears in a printed help module. 


XH2__Left-justifies, underscores, and highlights 
text (HP3). 


XH3__Left-justifies and highlights text (HP2). 
XH4 __Left-justifies and underscores text (HP1). 


Example: Sample Headings 


This example shows how extended help headings 
are highlighted and justified. 


UIM Source 


:XH1.Main Subject 

:p.Here's a paragraph. 
:XH2. Topic 

:p.Another paragraph. 
:XH3.Subtopic 

:p.Still another paragraph. 
:XH4.A Four Heading 
:p.Still another paragraph. 


Results: 

Main Subject 

Here's a paragraph. 
Topic 

Another paragraph. 
Subtopic 

Still another paragraph. 


A Four Heading 


Still another paragraph. 


XMP Tag 


XMP (Example) 


p>—:XMP.—:EXMP. 


>< 


The example (XMP) tag identifies an example of 
computer input or output. The XMP tag requires a 
matching end tag. These tags are only allowed in 
information areas and help areas. 


Examples can occur anywhere in text, except in 
other examples. The body of an example is com- 
posed of the text between the XMP tag and the 
EXMP tags. 


The normal formatting of text is suspended within 
an example; that is, the lines are not concat- 
enated. 


Note: Care should be taken when using exam- 
ples within lists, because example text that does 
not fit on a line wraps to column one of the next 
line. The current left margin changes when 
nested lists are formatted. If there is help informa- 
tion containing examples imbedded at various 
locations, including within lists, it may not look the 
same each time and can cause undesirable 
results. An example is indented 4 spaces from 
the current margin. Help modules displayed in 
full-screen format or in an extended help window 


are indented by 4 bytes. Therefore, the formatting 
width initially is 10 bytes less than the width speci- 
fied on the help module. When the XMP tag 
appears in an information area, the formatting 
width initially is 6 bytes less than the width speci- 
fied on the panel tag. 


Example: Formatting an Example 


This example illustrates how to use an example. 


UIM Source 

Some normal text... 
:xmp. 

This is an example 
right here 

:exmp. 


Results: 


Some normal text... 


This is an example 
right here 
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XMP Tag 
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Dialog Commands 


Appendix B. UIM Dialog Commands 


Dialog commands are special functions, recog- 
nized only by the UIM, that equate actions entered 
by a user with screen management functions. 
Dialog commands differ from CL commands in 
that they cannot be entered on a command line 
nor are they valid outside the scope of the UIM. 


Exactly what function the UIM performs for each 
dialog command depends largely on the type of 
screen being presented and other attributes 
defined by the function key, key list item (KEYI), 
menu item (MENUI), list action (LISTACT), or pull- 
down field choice (PDFLDC) language tags. For 
more information on the language tags, see 
Appendix A, “UIM Panel Group Definition 
Language” on page A-1. 


Some dialog commands are defined in terms of 
the content of the current command line, the posi- 
tion of the cursor, and the type of screen. Dialog 
commands also affect messages specified by the 
application, by the condition evaluation, and by 
calling the general exit. For example, some dialog 
commands cause condition evaluation to be 
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bypassed, while others cause the calling of the 
general exit to be bypassed. 


Dialog commands can be assigned to the fol- 
lowing: 


e Menu items 

e Function keys 

¢ Options on action lists 

¢ Hypertext links 

e Pull-down field choices 

e ENTER and SELECT attributes of the PANEL tag 


Not all dialog commands are allowed in all of 
these situations. For example, the dialog com- 
mands PAGEUP and PAGEDOWN cannot be 
assigned to options of an action list because they 
apply to the entire screen, and not to an individual 
list entry. 


For a summary of the valid uses of the dialog 
commands, see Table B-1 on page B-2. Fora 
summary of the effect of the different dialog com- 
mands, see Table B-2 on page B-3. Later in this 
appendix, there is a detailed description of each 
dialog command. 


B-1 


Dialog Commands 


Table B-1. Summary of the Valid Uses of Dialog Commands 


Valid Uses 
ENTER SELECT 

Dialog Pull-down on on 
Command Function Menu Menu List PANEL PANEL Hypertext 
Name Key Choices Item Action Tag Tag Link Action 
ACTIONS Xx x3 
CALL xX Xx Xx Xx Xx 
CANCEL Xx xX 
CHGVIEW xX x2 
CMD Xx Xx Xx Xx xX 
CMDLINE xX x2 
DSPHELP x2 Xx 
ENTER Xx 
EXIT x2 Xx 
EXTHELP x2 
HELP Xx 
HELPHELP x2 
HELPIDX x2 
HOME Xx 
KEYSHELP x2 
MENU Xx x2 Xx 
MOREKEYS 
MOVETOP xX 
MSG X Xx 
PAGEDOWN Xx 
PAGEUP Xx 
PRINT X 
PROMPT1 Xx 
PULLDOWN x3 
RETRIEVE Xx x2 
RETURN Xx Xx Xx Xx 
Notes: 


1 PROMPT becomes CALL or RETURN when processing a cursor-sensitive prompt defined by the PROMPT attri- 
bute of a DATAI, DATAIX, or LISTCOL language tag. 


2 Valid only when ACTFOR=PANEL is specified on the PDFLDC tag. 
3 Valid only when MBAR attribute is specified on the PANEL tag. 
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Dialog Commands 


Table B-2. Summary of the Effects of Dialog Commands 


Effects 
Stop Dis- 

Dialog playing Call 
Command User Mes- Evaluate General 
Name VARUPD on KEYI or PDFLDC Tag! sages2 Conditions Exit 
ACTIONS No No No No 
CALL Yes or No Yes Yes Yes 
CANCEL Yes or No Yes N/A Yes 
CHGVIEW Yes Yes Yes Yes 
CMD Yes or No Yes Yes Yes 
CMDLINE No No No No 
DSPHELP No No No No 
ENTER Yes N/A3 N/A3 N/AS 
EXIT Yes or No Yes N/A Yes 
EXTHELP No No No No 
HELP No No No No 
HELPHELP No No No No 
HELPIDX No No No No 
HOME Yes Yes Yes Yes 
KEYSHELP No No No No 
MENU Yes Yes Yes Yes 
MOREKEYS No No No No 
MOVETOP Yes No No No 
MSG N/A Yes Yes Yes 
PAGEDOWN Yes6 No No Yes6 
PAGEUP Yes6 No No Yes6 
PRINT No No No No 
PROMPTS Yes or No Yes Yes Yes 
PULLDOWN No No No No 
RETRIEVE No No No No 
RETURN Yes or No Yes N/A Yes 
Default4 N/A Yes Yes Yes 


Notes: 


1 VARUPD attribute applies only when the action is assigned to a function key or pull-down choice. When ACTFOR=LIST is 
specified on the PDFLDC tag, VARUPD is YES. 


2 The UIM stops displaying messages generated by an application (user messages) when another function is about to start. 
HELP can become a function if the help is for a command and the user directly starts the prompt and processing of the 
command from the help screen. 


3 These ENTER values are not applicable (N/A) because ENTER always equates with another function by the time these 
actions are performed. 


4 The UIM displays the panel again for the default ENTER or SELECT action. 


5 PROMPT becomes CALL or RETURN when processing a cursor-sensitive prompt defined by the PROMPT attribute of a DATAI, 
DATAIX, or LISTCOL language tag. 


6 When PAGEUP and PAGEDOWN apply to the message area, an information area, or a menu area, these values are not 
applicable. 
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CALL Command 


The VARUPD Attribute 


One of the main qualifiers of a function is the 
VARUPD attribute of the KEY! (key list item) and 
PDFLDC (pull-down field choice) language tag. 
This attribute defines whether or not dialog vari- 
ables and list entries should be updated with 


values entered by the user. It also defines 
whether the function associated with the key 
should be processed if errors are detected while 
validity checking the values of input fields on the 
display. Most dialog commands assume a partic- 
ular value for VARUPD that cannot be overridden by 
the panel definition. The following is a summary 
of the effect of VARUPD: 


Effect of VARUPD Attribute 


Type of Action VARUPD=YES 


VARUPD=NO 


Returning control to the appli- 
cation that called the 
QUIDSPP API. 


sages. 


All validity checking is per- 
formed, and dialog variables 
and list entries are updated 
when correct. When one or 
more variables fail the validity 
checking, the panel is dis- 
played again with error mes- 


No validity checking is performed and no 
updates are made to the dialog variables and 
list entries. Changes made to the input field 
by the user since the last operation are lost. 
The values entered by the user can some- 
times be recovered by calling QUIDSPP and 
specifying yes on the redisplay parameter. 
For more information, see the System API 
Reference. 


An action performed under 
the control of the UIM without 
returning to the application 


sages. 


All validity checking is per- 
formed, and dialog variables 
and list entries are updated 
when correct. When one or 
more variables fail the validity 
checking, the panel is dis- 
played again with error mes- 


No validity checking is performed and no 
updates are made to the dialog variables and 
list entries. Contents of the input fields are 
saved by the UIM and are used when dis- 
playing the panel again, providing updates 
have not been made that make the saved 
values obsolete. For example, changing a 
dialog variable that was displayed on the 
saved panel causes the saved value to be dis- 
carded and the new value shown when the 
panel is displayed again. 


ACTIONS (Menu Bar Cursor 
Action) 


>>—ACTIONS >< 


Alternates the cursor position between the panel 
and the menu bar. The Common User Access 
(CUA) guidelines recommend this function be 
assigned to F10. 


When the ACTIONS function key is pressed, the 
UIM saves the information where the cursor was 
located and moves the cursor to the first choice 
on the menu bar. If the ACTIONS function key is 
pressed again, the cursor returns to its previous 
location before it was moved to the menu bar. If 
the user moves the cursor to the menu bar area 
using the cursor movement keys (arrow keys) and 
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then presses the ACTIONS function key, the UIM 
determines the best position for the cursor. 


Messages: No messages are issued by the UIM 
during processing. 


CALL (Call Program) 


»>>—CALL—dialog-variable-name————_»< 


Calls an application program and allows applica- 
tions to link programs and screens together. 


The call function calls by address, by name, or by 
an extended program model (EPM) call. 


For best performance, use call by address. If call 

by address is not feasible, use the call by name or 
an EPM call with a library qualified program name 

(do not use *LIBL). 


For a description of the interface between the UIM 
and the program being called, see the section 
called "User Interface Management EXIT 
Program" in the System API Reference. The 
CALL dialog command can be used with the fol- 
lowing: 


e Menu item action 

e Function key action 

e Action list option 

¢ Action list exit 

¢ General panel exit 

¢ Default enter action 

¢ Application format exit 
¢ Contextual prompt exit 
e Pull-down choice action 


The CALL dialog command cannot be used on 
menu objects created using the Create Menu 
(CRTMNU) command, but can be used within a 
panel group object created using the Create Panel 
Group (CRTPNLGRP) command. If calling a 
program is the desired result of a menu option in 
an external menu, use the CMD dialog command 
to submit the CALL CL command. The user must 
have the proper authority to the CALL CL 
command and the program being called. 


Required Parameter 


dialog-variable-name 
Specifies a dialog variable containing the call 
information as described below for each of the 
three types of call. 


Call by address 
This type of call is used within OS/400 
system programs to allow calls of other 
system modules. Define the specified 
dialog variable with BASETYPE='PTR'. 
When the call function is requested, the 
dialog variable must contain a system 
pointer to the program. Ensure the proper 
authority is contained in the pointer. 


Call by name 
Allows calling an application program using 
a qualified name of a program object. 
Define the specified dialog variable with 
BASETYPE='CHAR 20'. When the call func- 
tion is requested, the first 10 characters of 
the dialog variable must contain the name 
of the program object. The second 10 
characters must contain the name of the 
library where the program resides. The 


CALL Command 


program and library names should be left 
justified and put in uppercase unless a 
quoted object name is used. 


Call by extended program model (EPM) 
This type of call allows calling an entry 
point in an EPM language program. The 
UIM uses the QPXXCALL interface to 
make the call. Define the specified dialog 
variable with BASETYPE='CHAR 130'. When 
the call function is requested, the dialog 
variable must contain the following: 


Characters Contents 


1-20 The name of the EPM 
program object and the name 
of the library that the object 


resides in 
21-120 The name of the external 
entry point to be called 
121-130 The name of the environment 


to which the entry point 
belongs 


Because UIM is simply passing this infor- 
mation to the QPXXCALL language inter- 
face program, ensure that the contents of 
the dialog variable adhere to the require- 
ments defined by QPXXCALL. When UIM 
calls the QPXXCALL program, the EPM 
environment is implicitly started and 
remains active until explicitly deleted. 


Note: There is a high performance over- 
head for calling an EPM program. If pos- 
sible, call by address or call by name 
instead. The support for calling an EPM 
program is provided for cases where, due 
to application design, an EPM program is 
used as the target of the CALL dialog 
command. 


VARUPD Value: The CALL dialog command 
does not have a predefined VARUPD value. When 
CALL is assigned to a function key, the VARUPD 
value of the function key dictates whether or not to 
perform validity checking and then updates the 
dialog variables. 


Messages: The following errors may be encoun- 
tered during processing: 


e Program not found. 
¢ Not authorized to specified program. 
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CHGVIEW Command 


¢ Number of parameters for specified program 
is not valid. 

e Program saved with STG(*FREE). 

e Any exception signalled by the QPXXCALL 
language interface program. 


The UIM does not stop processing if these errors 
occurred on a call for the general panel exit, on a 
call for the list action exit, and on application for- 
matted area calls. 


For all other types of calls, the UIM ends the 
action it was performing. In most cases, this 
involves displaying the panel again with an error 
message indicating that the program call was not 
successful. 


CANCEL 


NOSET 
>>— CANCEL : — >< 
SET 


Backs up one screen and is used with a menu 
item action or a function key action. 


If the current screen was called by the QUIDSPP 
API, the function parameter contains an indication 
that CANCEL was requested. 


If the current screen is a menu called from the 
previous screen via the menu fast-path function 
(for example, entering GO on the command line), 
the UIM displays the previous screen. 


Optional Parameter 


NOSET|SET 
Indicates whether the cancel flag is set. 
NOSET means that the cancel flag is not set; 
this is the default value. SET means that the 
cancel flag is set. For more information on 
the cancel flag, see “Folding Up a List Panel” 
on page 17-26. 


VARUPD Value: CANCEL does not have a pre- 
defined VARUPD value. When CANCEL is assigned 
to a function key, the VARUPD value of the function 
key determines whether or not to perform validity 
checking and then updates the dialog variables. 


Messages: No messages are issued during pro- 
cessing. 
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CHGVIEW (Change View) 


>>—CHGVIEW >< 


Changes the displayed view of a list and can only 
be assigned to a function key or a pull-down field 
choice action. 


If there are several columns of information that a 
user needs to see, and all the columns do not fit 
on the display, you can change the view so the 
user sees one set of columns and then another 
set of columns. This continues until all the 
columns of information are viewed. 


You can specify several different ways to present 
a list area on the LISTVIEW language tag and 
which columns belong to each view. List views 
are numbered sequentially starting with 0. For 
example, if a list areas has five presentation 
views, the views are numbered from 0 to 4. The 
first LISTVIEW tag in the panel source for the list 
area defines view 0, the second LISTVIEW tag in 
the panel source for the list area defines view 1, 
and so on for all LISTVIEW tags in the list area. 


With the CHGVIEW dialog command, you can 
switch views. The function operates in a circular 
fashion. For example, if the current view is 3, 
CHGVIEW presents view 4 (if there is a view 4), 
or back to view 0 if there is not a view 4. Applica- 
tions can specifically select a view by changing 
the dialog variable coded on the VIEW attribute of 
the LIST tag. The UIM also modifies this dialog 
variable whenever the CHGVIEW dialog command 
is performed. 


Which list the request applies to depends on the 
cursor position. The rules are very similar to 
those for the PAGEDOWN and PAGEUP dialog 
commands. 


e If the cursor is in a list area defined as having 
multiple views, the request applies to that 
area. 


e If the cursor is not in a list area defined as 
having multiple views, the request applies to 
the first list area on the screen that does have 
multiple views. 


Parameters: None 


VARUPD Value: The CHGVIEW dialog 
command always operates with VARUPD=YES 
and the following occurs: 


e Validity checking is always performed. 

e Valid values are processed and the dialog var- 
iables are updated. 

e Any failures from validity checking prevent 
changing the view and the screen is displayed 
again with the appropriate error messages. 


Messages: No messages are issued during pro- 


cessing unless there are errors from a validity 
check. 


CMD (System Command) 


>>—CMD—command-text >< 


Submits a CL or OCL command to the system 
command. 


Parameter 


command-text 
All text following the CMD dialog command is 
treated as a command and is submitted to the 
system for processing. Whether the 
command is native or System/36 environment 
is determined by the system, not by the UIM. 


The command string may contain the names 
of dialog variables to be substituted into the 
command string before the UIM submits the 
command to the system. Each dialog variable 
name must be preceded by an ampersand (&) 
and followed by a period (.). Although the 
ending period is not required, its use is recom- 
mended to avoid ambiguity. 


Before submitting the command, the UIM per- 
forms substitution for dialog variables. Each 
dialog variable specified as part of the 
command string is replaced by its displayable 
value. This value is always calculated from 
the current value of the dialog variable. 


VARUPD Value: The CMD dialog command 
does not have a predefined VARUPD value. When 
CMD is assigned to a function key or pull-down 
field choice, the VARUPD attribute on the KEYI or 
PDFLDC language tag dictates whether or not to 
perform validity checking and then updates the 


DSPHELP Command 


dialog variables. Because substituting commands 
depends on the values of dialog variables, care 
should be taken when using VARUPD=NO. 


Messages: No messages are issued during pro- 
cessing unless there are errors from a validity 
check. 


Hint: Because these commands are not logged 
to the job log, it is sometimes difficult to discover 
and correct command syntax errors. One way to 
see the command after all dialog variables have 
been substituted is to make the command the 
value of the message on a SNDMSG command 
as follows: 


SNDMSG MSG (command here) TOUSR (*REQUESTER) 


CMDLINE (Command Line) 


>>—CMDLINE >< 


Displays a pop-up window containing a command 
line on the bottom of the display. 


Parameters: None 


Messages: No messages are issued during pro- 
cessing. 


DSPHELP (Display Help) 


>>—DSPHELP—he lp-module-name-———_____ 


> | >< 


Lpanel -group L a 
product-1ibrary 


Displays a specified UIM help module. 


Required Parameter 


help-module-name 
Specifies the name of the help module to be 
displayed. 


Optional Parameter 
qualified-panel-group-name 
Specifies the name of the panel group con- 


taining the help module. If it is not specified, 
then 1) the help module must be from the 
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EXIT Command 


same panel group that contains the DSPHELP 
dialog command, or 2) the help module must 
be imported from another panel group by 
using an IMPORT tag. 


product-library 
Specifies the name of a library which 
becomes the product library when the help 
module is displayed. This parameter is only 
used when the DSPHELP dialog command is 
used for a hypertext link action. 


Messages: No messages are issued during pro- 
cessing. 


ENTER 


>>—ENTER >< 


Allows processing of an action and is only allowed 
on the Enter key. 


For more information, see “Considerations for 
Using the ENTER, HELP, and PROMPT Dialog 
Commands.” 


Parameters: None 


VARUPD Value: The ENTER dialog command 
always operates with VARUPD=YES and the fol- 
lowing occurs: 


e Validity checking is always performed. 

e Valid values are processed and the dialog var- 
iables are updated. 

e Any failures from validity checking stop the 
operation. The display is shown again with 
the appropriate error messages. 


Messages: Any messages resulting from submit- 
ting or canceling the commands are displayed on 
the message line. Additional messages can be 
sent if validity-checking errors are encountered. 


Considerations for Using the ENTER, 
HELP, and PROMPT Dialog 
Commands: The actions performed for 
ENTER, HELP, and PROMPT depend heavily on 
the type of display and contents of the command 
line. These dialog commands can be assigned 
only to function keys, and they have different char- 
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acteristics than other dialog commands. These 
dialog commands are more like action qualifiers; 
things used to determine or modify a more con- 
crete action like a system command string. 


For example, an action list panel describes 
several actions that are performed, based on the 
contents of various fields. The ENTER and 
PROMPT dialog commands, and to a lesser 
extent HELP dialog commands, are initially 
requested, but serve only to describe how the rest 
of the panel is interpreted. They are not sufficient 
by themselves to describe what should be done. 


Some important aspects to remember when 
reading descriptions of these dialog commands 
are: 


e Amenu with a command line can contain a 
selection from a menu item or a command. If 
the first nonblank character string is unquoted 
and contains only numeric values, it is inter- 
preted as a menu item. Otherwise, it is 
assumed to be a command. 


e An action list with a command line can contain 
parameter strings or commands. If any entry 
on an action list is selected, any string in the 
command line is treated as a parameter list. 
Otherwise, it is treated as a command. 


EXIT (Exit Display) 


NOSET: 
>>—EXIT : — >< 
SET 


Allows the user to back out of groups of displays. 


If the current display was displayed using 
QUIDSPP API, the UIM sets the function 
requested parameter indicating that the EXIT 
dialog command was requested. It is up to the 
application to determine what must be done next. 


If the current display is a menu called from a 
series of displays, the UIM presents the display 
where the MENU command was initially 
requested. The EXIT dialog command backs 
completely out of a series of menus. 


Optional Parameter 


NOSET|SET 
Indicates whether the job's exit flag is set. 
NOSET means that the exit flag is not set; this 
is the default. SET means that the exit flag is 
set. For more information on the exit flag, see 
“Folding Up Multiple Panels When EXIT Is 
Requested” on page 17-24. 


VARUPD Value: The EXIT dialog command 
does not have a predefined VARUPD value although 
the user interface style implies VARUPD=NO 
should normally be used. When EXIT is assigned 
to a function key or pull-down choice, the VARUPD 
value of the function key dictates whether or not to 
perform validity checking and then updates the 
dialog variables. 


Messages: No messages are issued during pro- 
cessing. 


EXTHELP (Extended Help) 


p>>—EXTHELP >< 


Displays the extended help for the panel. 


Parameters: None 


HELP 


>>—HELP. >< 


Displays help information. The Common User 
Access (CUA) guidelines recommend assigning 
this to the Help and F1 keys. 


The specific action taken (and help text displayed) 
depends on the screen type, cursor position, and 
so on. For the UIM rules, see “Defining Contex- 
tual Help” on page 17-16, and for more informa- 
tion on the specific attributes, see “Considerations 
for Using the ENTER, HELP, and PROMPT Dialog 
Commands’ on page B-8. 


Parameters: None 


VARUPD Value: It is always VARUPD=NO. No 
validity checking is performed on the current con- 
tents of the current panel and no updates to dialog 
variables are made. 


HOME Command 


Messages: The message Help information is 
not available can be issued during processing 
and can occur if the user chooses to delete or not 
install help text supplied by the system. 


Additional messages are also possible when help 
is requested for a specific command on a 
command line. Possible messages might be that 
the command does not exist, or the user might not 
have authority to it. If these messages are issued, 
they appear as the first message in the message 
area. Messages describing other conditions on 
the screen can still be viewed by scrolling forward. 


HELPHELP 


>>—HELPHELP >< 


Displays information about how to use the help 
facilities for contextual help, extended help, help 
on function keys, and the help index from help 
panels. The HELPHELP dialog command can be 
coded only on pull-down choices for menu bars. 


Parameters: None 


Messages: No messages are issued during pro- 
cessing. 


HELPIDX 


p>—HELPIDX >< 


Begins the index search function for the SCHIDX 
attribute specified on the panel group tag. Users 
may select a topic in the index to be displayed or 
printed. The HELPIDX dialog command can be 
coded only on pull-down choices for menu bars. 


Parameters: None 


Messages: No messages are issued during pro- 
cessing. 


HOME (Display Home Menu) 


>>—HOME >< 


Appendix B. UIM Dialog Commands B-9 


MOREKEYS Command 


Displays the job's home menu. This menu is 
added to the stack of menus. It does not imply 
returning to the beginning of the stack of menus. 
The HOME dialog command can be used only on 
function keys. 


Note: HOME is allowed only on panels con- 
taining a menu area. 


Parameters: None 


VARUPD Value: The HOME dialog command 
always operates with VARUPD=YES and the fol- 
lowing occurs: 


e Validity checking is always performed. 

e Valid values are processed and the dialog var- 
iables are updated. 

e Any failures from validity checking prevent the 
operation and the screen is displayed again 
with the appropriate error messages. 


Messages: No messages are issued during pro- 
cessing. 


KEYSHELP 


>>—KEYSHELP >< 


Displays the help for the function keys on the dis- 
played panel. The Common User Access (CUA) 
guidelines recommend assigning this to the F1 
key. 


Messages: No messages are issued during pro- 
cessing. 


MENU 


p>>—MENU—qual i fied-menu-name-——_» 


RTNPNT- 
> : >< 
NORTNPNT 


Displays a subsequent menu as a result of 
selecting a menu item or pressing a function key. 
Required Parameter 


qualified-menu-name 
Specifies the qualified name of the menu to 
be displayed. 
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Optional Parameter 


RTNPNT|NORTNPNT 
This parameter indicates whether the current 
menu is considered a return point when the 
dialog command is requested. This parameter 
functions the same as the return point 
(RTNPNT) parameter of the GO CL 
command. RTNPNT indicates that the current 
menu is returned when the Exit key is 
pressed; this is the default. No return point 
(NORTNPNT) indicates to not return to the 
current menu when the Exit key is pressed. 


This parameter has no effect when it is coded 
in a panel group object using the Create 
Panel Group (CRTPNLGRP) command. It is 
meaningful only when it is used in a menu 
object created using the Create Menu 
(CRTMNU) command. 


Messages: No messages are issued during pro- 
cessing. 


MOREKEYS (Display More 
Function Keys) 


>>—MOREKEYS >< 


Displays an additional list of active function keys 
when they cannot all fit on the panel. The action 
of the MOREKEYS dialog command can be 
assigned only to Function Key F24. When it is, it 
cannot be conditioned using the COND attribute of 
the key item (KEYI) language tag. 


If an application codes ACTION=MOREKEYS on 
the KEYI tag, the UIM manages the situation if all 
of the function key descriptions do not fit on the 
panel at once. 


When a panel is displayed with a KEYL (Key List) 
language tag using the MOREKEYS dialog 
command, the UIM gathers a list of all currently 
active function keys. This is based on the priority 
assigned to each key item on the PRIORITY attri- 
bute of the KEYI language tag. The UIM attempts 
to fit as many of the function keys as possible in 
the function key area of the panel. 


If not all of the function key descriptions fit in the 
area, the UIM enables the function key assigned 
to the MOREKEYS dialog command and places 
the descriptions of the function keys on the panel. 
If all of the descriptions of the function keys fit, the 
function key assigned to the MOREKEYS dialog 
command is not enabled. 


If a user presses the function key assigned to the 
MOREKEYS dialog command, the UIM starts 
where it left off in the key list and gathers as many 
active descriptions of function keys that fit in the 
function key area in order of priority. The function 
key assigned to the MOREKEYS dialog command 
is enabled. 


This process continues until the end of the key list 
is reached. If the MOREKEYS dialog command is 
selected again, the UIM starts back at the begin- 
ning of the key list and begins processing the 
MOREKEYS dialog command again. 


Parameters: None 


Messages: No messages are issued during pro- 
cessing. 


MOVETOP (Move to Top) 


>>—MOVETOP >< 


Moves a cursor-selected line to the top of the 
scrollable information area. 


When a function key assigned to this dialog 
command is pressed, the UIM moves the line con- 
taining the cursor to the top of the scrollable area. 
If the cursor is on a blank line inserted by the UIM 
(paragraph separators, and so on), the next line is 
moved to the top of the scrollable area. 


The MOVETOP dialog command applies only to 
information areas, and is intended primarily to 
allow users of online text to position the informa- 
tion in the most readable manner. For example, 
an entire chart positioned on one display is easier 
to read than a chart that appears on two displays. 


Parameters: None 


PAGEDOWN Command 


VARUPD Value: The MOVETOP dialog 
command operates with VARUPD=YES (except 
when scrolling the message line) and the following 
occurs: 


e Validity checking is always performed. 

e Valid values are processed and the dialog var- 
iables are updated. 

e Any failures from validity checking prevent the 
operation and the panel is displayed again 
with the appropriate error messages. 


Messages: The UlM can issue Cursor not 
positioned on valid line. 


MSG (Display Message) 


>>—MSG—imes sage-id > 


> 


>< 


Lr, ified-message-fi jesnome 


Displays a message on the message line. It can 
only be assigned as the default enter action or the 
default selection action to perform when the Enter 
key is pressed, and the UIM cannot find any other 
specific function to perform. 


One intended use of this dialog command is to 
inform the user that they must select an option or 
press a function key. 


Required Parameter 


message-id 
Specifies the message identifier of the 
message to be displayed. 


Optional Parameter 


qualified-message-file-name 
Specifies the qualified name of the message 
file containing the message. It defaults to the 
message file specified on the DFTMSGF attribute 
of the PNLGRP tag. 


VARUPD Value: Because the MSG dialog 
command can only be specified on the ENTER attri- 
bute of the PANEL tag, VARUPD has no meaning. 
The VARUPD value is defined by the function key 
assigned to the ENTER action. 


PAGEDOWN 
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PRINT Command 


>>—PAGEDOWN >< 


Scrolls forward by one screen or panel and can be 
assigned to only a function key. 


When processing incomplete lists, selecting scroll 
areas, and specifying VARUPD=YES, the process 
is the same for the PAGEDOWN dialog command 
as it is for the PAGEUP dialog command. 
Parameters: None 


Messages: UIM can issue Already at bottom of 
area. 


Additional messages can be sent if validity 
checking encounters errors. 


PAGEUP 


>>—PAGEUP. >< 


Scrolls backward by one screen or panel and can 
be assigned to only a function key. 


If a full scrollable area of data is available to the 
UIM, or the scrollable area is complete, scrolling is 
performed without intervention of the application. 

If the scrollable area is an action list with selected 
actions, none are performed at this time. 


A special case exists where an incomplete list is 
displayed and the PAGEUP scroll results in an 
incomplete panel. In this case, the UIM calls the 
program specified to add additional list entries or 
mark the list complete. 


For screens and panels with multiple scrollable 
areas, the position of the cursor determines what 
is scrolled. The rules are as follows: 


e lf the cursor is in a scrollable area, that area 
is selected. The message line is considered a 
scrollable area. 
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The boundaries of a scrollable area are 
defined by the top and bottom line of a menu, 
information, list, or data area, although not all 
information in that area (such as instruction 
lines) is actually scrolled. 


e If the cursor is outside a scrollable area, the 
first scrollable area on the panel (top to 
bottom) is selected for scrolling. 


Parameters: None 


VARUPD Value: PAGEUP operates with 
VARUPD=YES except when scrolling the 
message line, and the following occurs: 


e Validity checking is always performed. 

e Valid values are processed and the dialog var- 
iables are updated. 

e Any failures from validity checking prevent 
scrolling and the panel is displayed again with 
the appropriate error messages. 


When scrolling the message line, the PAGEUP 
dialog command operates as if VARUPD=NO is in 
effect. Fields need not be correct and dialog vari- 
ables are not updated. 


Messages: UIM can issue Already at top of 
area. 


Additional messages can be sent if validity 
checking encounters errors. 


PRINT (Print Display) 


>>—PRINT- >< 


Prints the current display and can be assigned 
only to the 5250 PRINT key. 


Parameters: None 
VARUPD Value: Does not apply. 
Messages: No messages are issued during pro- 


cessing unless errors are found during validity 
checking. 


PROMPT 


>>—PROMPT- >< 


Prompts for commands, action list options, and 
entry fields and can be assigned only to function 
keys. Its specific function depends on the fol- 
lowing: 


e Type of screen being managed 
¢ Location of the cursor 
¢ Contents of the command or parameter line 


Parameters: None 


VARUPD Value: For more information, see 
“Prompting an Entry Field” and “Prompting an 
Action List Option or Command.” 


Messages: Any messages resulting from submit- 
ting or canceling the commands are displayed on 
the message line. In addition, the UIM can issue 
the following messages: 


¢ The prompt attempt for the menu item was 
not valid. 

e Cursor is in a location where the prompt 
function is not allowed. 


Additional messages can be sent if errors from 
validity checking are encountered. 


Prompting an Entry Field: The prompt 
function becomes a CALL or RETURN function 
based on the prompt definition specified on the 
PROMPT attribute of the associated panel definition 
tag. Prompting an entry field should be assigned 
to the F4 key. 


When prompting an entry field, VARUPD processing 
is done if it is specified on the definition of the 
function key. 


If VARUPD=YES is specified for the function key, 
the following occurs: 


¢ Validity checking is always performed 

e Valid values are processed and the dialog var- 
iables are updated 

e Any failures from validity checking prevent 
prompting and the panel is displayed again 
with the appropriate error messages. 


PROMPT Command 


If VARUPD=NO is specified for the function key, 
the application program can get access to the 
keyed data that is not verified by using the 
DSPVALUE attribute of the tag where the prompt 
was defined. 


For more information about entry field prompting, 
see the description of the PROMPT attribute for the 
following tags found in Appendix A, “UIM Panel 
Group Definition Language” on page A-1. 


¢ Data item (DATAI) 
¢ Data item Extender (DATAIX) 
e List column (LISTCOL) 


Prompting an Action List Option or 


Command: When prompting an option on an 
action list or command line, the PROMPT dialog 
command always operates with VARUPD=YES 
and the following occurs: 


e Validity checking is always performed. 

e Valid values are processed and the dialog var- 
iables are updated. 

e Any failures from validity checking prevent 
prompting and the panel is displayed again 
with the appropriate error messages. 


The prompt function results in either submitting a 
command string to the system or calling an appli- 
cation program. This occurs according to the fol- 
lowing rules: 


e |f the command line contains a menu item, an 
error is sent. The UIM does not support 
prompting for menu items. 


e If the cursor is on the command line or in the 
option column and if the panel has an action 
list panel with options specified, the UIM 
selects the PROMPT action associated with 
each selected option. The PROMPT action 
can either be to submit a command to the 
system or to call an application program. 


If an option is selected that does not have a 
defined prompt action, action list processing 
stops, and the panel is displayed again with 
an error message. The error message indi- 
cates that the user cannot prompt for the 
selected option. In this case, the selected 
option number is displayed with error 
emphasis. 


The contents of the command line are param- 
eters for the list action. These parameters 
can be accessed by defining a dialog variable 
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RETURN Command 


for the UIM to update. The update is with the 
contents of the command line when the action 
list is processed. For more information see 
the LIST tag in Appendix A, “UIM Panel 
Group Definition Language” on page A-1 


Each individual option receives a separate 
prompt. The UIM does not apply information 
added during prompting from one command to 
another. 


When the prompt action is to call an applica- 
tion program, the option is processed without 
prompting by the UIM. When the UIM calls 
the application program, an indication is given 
that the user requested the prompt function. It 
is the responsibility of the application program 
to provide its own version of prompting. 


e If the command line contains a command, the 
command is submitted for prompting and pro- 
cessing. The command can then be run or 
canceled through normal prompter functions. 
Depending on the environment the job is 
running in, the system can pass the command 
to the System/36 environment or REXX. 


If the command line was blank (a subclass of 
assuming it contains a command), the Major 
Command Groups menu is displayed. 


For additional information about the PROMPT 
dialog command, see “Considerations for Using 
the ENTER, HELP, and PROMPT Dialog 
Commands” on page B-8. 


PULLDOWN (Display Pull-Down 
Menu) 


>>—PULLDOWN >< 


Displays the first pull-down menu of the menu bar. 


Parameters: None 


RETRIEVE (Retrieve Command 
String) 


p>>—RETRIEVE >< 


Displays the previously entered command. 


B-14 Application Display Programming V4R1 


The UIM keeps a series of commands entered on 
command lines. When the RETRIEVE dialog 
command is issued, the previous command is dis- 
played on the command line. If the RETRIEVE 
dialog command is issued again before any other 
function is performed, the next most recent 
command is displayed. 


Menu item selections and parameter strings 
cannot be retrieved. Also, commands submitted 
via the CMD dialog command cannot be retrieved. 


Parameters: None 


VARUPD Value: The RETRIEVE dialog 
command always operates with VARUPD=NO. 
No validity checking is performed on the contents 
of the current panel and no updates are made to 
the dialog variables. 


Messages: No messages are issued during pro- 
cessing. 


RETURN (Return Control to 
Application) 


p>>—RETURN—n >< 


Provides the application with a method of handling 
function keys, menu items, and pull-down choices 
by having the UIM return control to the application 
with the appropriate indication. 


Note: To provide the Refresh/Redisplay function 
for an application, use the RETURN dialog 
command. 


The effect of the RETURN dialog command can 
be obtained for action lists by using the ACTOR 
attribute of the LIST tag. This attribute determines 
whether or not the UIM should handle the action 
list. 


Required Parameter 


n_ This parameter specifies a numeric value from 
1 through 32767. This value is returned to the 
application, on the function requested param- 
eter of QUIDSPP API, when the RETURN 
function is encountered. 


VARUPD Value: The RETURN dialog command whether or not to perform validity checking and 


does not have a predefined VARUPD value. When then updates the dialog variables. 

RETURN is assigned to a function key, the 

VARUPD value of the function key determines Messages: No messages are issued during pro- 
cessing unless errors are found during validity 
checking. 


Appendix B. UIM Dialog Commands B-15 


B-16 Application Display Programming V4R1 


Appendix C. Feedback Area Layouts for Display Files 


This appendix contains Product-Sensitive Pro- The support provided by the high-level language 
gramming Interface and Associated Guidance you are using determines how to access this infor- 
Information. mation and how the data types are represented. 


See your high-level language manual for more 


Tables in this section describe the open and I/O information. 
feedback areas associated with any opened 


display file. The following information is presented 


for each item in these feedback areas: Open Feedback Area 
¢ Offset, which is the number of bytes from the 


start of the feedback area to the location of 


each item. 
e Data Type. 


e Length, which is given in number of bytes. 
¢ Contents, which is the description of the item 


and the valid values for it. 


The open feedback area is the part of the open 
data path (ODP) that contains general information 
about the file after it has been opened. It also 
contains file-specific information for display files, 
plus information about each device defined for the 
file. This information is set during open pro- 
cessing and may be updated as other operations 


For information about feedback area layouts for are performed. 
files other than display files, see the Data Man- 


agement book. 


Table C-1 (Page 1 of 3). Open Feedback Area 


Data 
Offset Type Length Contents 
0 Character 2 Open data path (ODP) type: 
DS Display, tape, ICF, save, printer file not being spooled, or diskette file 
not being spooled. 
DB Database member. 
SP Printer or diskette file being spooled or inline data file. 
2 Character 10 Name of the file being opened. If the ODP type is DS (for display files), this is 
the name of the display file. 
12 Character 10 Name of the library containing the file. For an inline data file, the value is *N. 
22 Character 10 Not applicable to displays. 
32 Character 10 Not applicable to displays. 
42 Binary 2 Not applicable to displays. 
44 Binary 2 Maximum record length. 
46 Character 2 Not applicable to displays. 
48 Character 10 Not applicable to displays. 
58 Binary 4 Reserved. 
62 Binary 4 Reserved. 
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Data 
Offset Type Length Contents 
66 Binary 2 File type: 
1 Display 
2 Printer 
4 Diskette 
5 Tape 
9 Save 
10 DDM 
11 ICF 
20 Inline data 
21 Database 
68 Character 3 Reserved. 
71 Binary 2 Number of lines on a display screen. 
73 Binary 2 Number of positions on a display screen. 
75 Binary 4 Not applicable to displays. 
79 Character 2 Not applicable to displays. 
81 Character 1 Not applicable to displays. 
82 Character 1 Not applicable to displays. 
83 Character 10 Reserved. 
93 Character 10 Reserved. 
103 Binary 2 Not applicable to displays. 
105 Binary 2 Maximum number of records that can be read or written in a block when using 
blocked record I/O. 
107 Binary 2 Not applicable to displays. 
109 Binary 2 Blocked record I/O record increase. Number of bytes that must be added to the 
start of each record in a block to address the next record in the block. 
111 Binary 4 Reserved. 
115 Character 1 Miscellaneous flags. 


Bit 1: Reserved. 


Bit 2: File with sharing 


0 File was not opened with sharing. 
1 File was opened with sharing (SHARE(*YES)). 


Bits 3-5: Not applicable to displays. 
Bit 6: Field-level descriptions 


0 ‘File does not contain field-level descriptions. 
1 File contains field-level descriptions. 


Bit 7: DBCS-capable file 


0 File is not DBCS-capable. 
1 File is DBCS-capable. 


Bit 8: Not applicable to displays. 
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Table C-1 (Page 3 of 3). Open Feedback Area 


Data 

Offset Type Length Contents 

116 Character 10 For display files, this is the name of the display device description that is the 
requesting program device. 

This field is supplied only when a device name of *REQUESTER is being 
attached to the display file by an open or acquire operation. Otherwise, this field 
contains *N. 

126 Binary 2 File open count. If the file has not been opened with sharing, this field contains 
a1. If the file has been opened with sharing, this field contains the number of 
programs currently attached to this file. 

128 Binary 2 Reserved. 

130 Binary 2 Not applicable to displays. 

132 Character 1 Miscellaneous flags. 

Bits 1-4: Not applicable to displays. 
Bit 5: Separate indicator area 
0 Indicators are in the I/O buffer of the program. 
1 Indicators are not in the I/O buffer of the program. The DDS 
keyword, INDARA, was used when the file was created. 
Bit 6: User buffers 
0 System creates I/O buffers for the program. 
1 User program supplies I/O buffers. 
Bit 7: Reserved. 
Bit 8: Not applicable to displays. 

133 Character 2 Open identifier. The value is unique for a full open operation (SHARE (*NO)) of 
a file or the first open operation of a file opened with SHARE(*YES). It allows 
you to match this file to an entry on the associated data queue. 

135 Binary 2 The field value is the maximum record format length, including both data and 
file-specific information such as: option indicators, response indicators, source 
sequence numbers, and program-to-system data. If the value is zero, then use 
the field at offset 44. 

137 Binary 2 Not applicable to displays. 

139 Character 1 Miscellaneous flags. 

Bits 1-3: Not applicable to displays. 
Bit 4: CCSID character substitution 
0 No substitution characters will be used during CCSID data con- 
version. 
1 Substitution characters may be used during CCSID data conver- 
sion. 
Bits 5-8: Reserved. 

140 Character Reserved. 

146 Binary 2 Number of devices defined for this ODP. For displays, this is determined by the 
number of devices defined on the DEV parameter of the Create Display File 
(CRTDSPF) command. 

148 Character Device name definition list. See “Device Definition List” on page C-4 for a 


description of this array. 
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Device Definition List open feedback area. The device definition list 
begins at offset 148 of the open feedback area. 


The device definition list part of the open feedback The offsets shown for it are from the start of the 
area is an array structure. Each entry in the array device definition list rather than the start of the 
contains information about each device attached open feedback area. 


to the file. The number of entries in this array is 
determined by the number at offset 146 of the 


Table C-2 (Page 1 of 2). Device Definition List 


Data 
Offset Type Length Contents 
Program device name. For display files, the value is the name of the device 
0 Character 10 description. 
10 Character 50 Reserved. 
Device description name. For display files, the value is the name of the device 
60 Character 10 description. 
70 Character 1 Device class. For displays, the device class is hex 01. 
Device type. 
hex 07 5251 Display Station 
hex 0B 5291 Display Station 
hex OD 5292 Display Station 
hex 12 5555-B01 Display Station 
hex 13 3270 Display Station 
hex 15 Graphic-capable device 
hex 16 Financial terminal 
hex 17 3180 Display Station 
hex 19 3277 DHCF Device 
hex 26 3179-2 Display Station 
hex 27 3196-A Display Station 
hex 28 3196-B Display Station 
hex 33 3197-C1 Display Station 
hex 34 3197-C2 Display Station 
hex 35 3197-D1 Display Station 
hex 36 3197-D2 Display Station 
hex 37 3197-W1 Display Station 
hex 38 3197-W2 Display Station 
hex 39 5555-E01 Display Station 
hex 3E 3476-EA Display Station 
hex 3F 3477-FG Display Station 
hex 40 3278 DHCF device 
hex 41 3279 DHCF device 
hex 42 ICF finance device 
hex 43 Retail communications device 
hex 44 3477-FA Display Station 
hex 45 3477-FC Display Station 
hex 46 3477-FD Display Station 
hex 47 3477-FW Display Station 
hex 48 3477-FE Display Station 
hex 4D Network Virtual Terminal display station 
hex 51 5555-C01 Display Station 
hex 52 5555-F01 Display Station 
hex 56 3476-EC Display Station 
71 Character 1 hex 58 5555-G01 Display Station 
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Table C-2 (Page 2 of 2). Device Definition List 


Data 
Offset Type Length Contents 
hex 59 5555-G02 Display Station 
hex 5D 3486-BA Display Station 
hex 5F 3487-HA Display Station 
hex 60 3487-HG Display Station 
hex 61 3487-HW Display Station 
hex 62 3487-HC Display Station 
72 Binary 2 Number of lines on the display screen. 
74 Binary 2 Number of positions in each line of the display screen. 
Bit flags. 
Bit 1: Blinking capability. 
0 __ Display is not capable of blinking. 
76 Character 2 1 Display is capable of blinking. 
Bit 2: Device location. 
0 Local device. 
1 Remote device. 
Bit 3: Acquire status. This bit is set even if the device is implicitly acquired 
at open time. 
0 Device is not acquired. 
1 Device is acquired. 
Bit 4: Invite status. 
0 Device is not invited. 
1 Device is invited. 
Bit 5: Data available status (only if device is invited). 
0 Data is not available. 
1 Data is available. 
Bit 6: Not applicable to displays. 
Bit 7: Requesting program device. 
0 Nota requesting program device. 
1 A requesting program device. 
Bit 8: DBCS device. 
0 Device is not capable of processing double-byte data. 
1 Device is capable of processing double-byte data. 
Bits 9-10: Reserved. 
Bit 11: DBCS keyboard. 
0 Keyboard is not capable of entering double-byte data. 
1 Keyboard is capable of entering double-byte data. 
Bits 12-16: Reserved. 
78 Character 1 Not applicable to displays. 
79 Character 1 Not applicable to displays. 
80 Character 50 Reserved. 
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information, such as the count of I/O operations, 


I/O Feedback Area reflects the number of operations on blocks of 
records and not the number of records. See your 

The results of I/O operations are communicated to high-level language manual to determine if your 

the program using OS/400 messages and I/O program uses blocked record I/O. 

feedback information. The I/O feedback area is 

updated for every I/O operation unless your The I/O feedback area consists of two parts: a 

program is using blocked record I/O. In that case, common area and a file-dependent area. 


the feedback area is updated only when a block of 
records is read or written. Some of the informa- 


tion reflects the last record in the block. Other Common I/O Feedback Area 


Table C-3 (Page 1 of 3). Common I/O Feedback Area 


Data 
Offset Type Length Contents 


0 Binary 2 Offset to file-dependent feedback area. 


2 Binary 4 Write operation count. Updated only when a write operation completes success- 
fully. For blocked record I/O operations, this count is the number of blocks, not 
the number of records. 


6 Binary 4 Read operation count. Updated only when a read operation completes success- 
fully. For blocked record I/O operations, this count is the number of blocks, not 
the number of records. 


10 Binary 4 Write-read operation count. Updated only when a write-read operation com- 
pletes successfully. 


14 Binary 4 Other operation count. Number of successful operations other than write, read, 
or write-read. Updated only when the operation completes successfully. This 
count includes update, delete, force-end-of-data, force-end-of-volume, change- 
end-of-data, release record lock, and acquire/release device operations. 


18 Character 1 Reserved. 
19 Character 1 Current operation. 


hex 01 Read or read block or read from invited devices 
hex 02 Read direct 

hex 03 Read by key 

hex 05 Write or write block 
hex 06 Write-read 

hex 07 Update 

hex 08 Delete 

hex 09 Force-end-of-data 
hex 0A Force-end-of-volume 
hex 0D Release record lock 
hex OE Change end-of-data 
hex OF Put delete 

hex 11 Release device 

hex 12 Acquire device 


20 Character 10 Name of the record format just processed, which is either: 


¢ Specified on the I/O request, or 
¢ Determined by default or format selection processing 


For display files, the default name is either the name of the only record format in 
the file or the previous record format name for the record written to the display 
that contains input-capable fields. Because a display file may have multiple 
formats on the display at the same time, this format may not represent the 
format where the last cursor position was typed. 
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Table C-3 (Page 2 of 3). Common I/O Feedback Area 


Data 

Offset Type Length Contents 

30 Character 2 Device class: 
Byte 1: 
hex 00 Database 
hex 01 Display 
hex 02 Printer 
hex 04 Diskette 
hex 05 Tape 
hex 09 Save 
hex 0B ICF 
Byte 2 (if byte 1 contains hex 01 for displays): 
hex 07 5251 Display Station 
hex OB 5291 Display Station 
hex OD 5292 Display Station 
hex 12 5555-B01 Display Station 
hex 13 3270 Display Station 
hex 15 Graphic-capable device 
hex 16 Financial terminal 
hex 17 3180 Display Station 
hex 19 3277 DHCF device 
hex 26 3179-2 Display Station 
hex 27 3196-A Display Station 
hex 28 3196-B Display Station 
hex 33 3197-C1 Display Station 
hex 34 3197-C2 Display Station 
hex 35 3197-D1 Display Station 
hex 36 3197-D2 Display Station 
hex 37 3197-W1 Display Station 
hex 38 3197-W2 Display Station 
hex 39 5555-E01 Display Station 
hex 3E  3476-EA Display Station 
hex 3F 3477-FG Display Station 
hex 40 3278 DHCF device 
hex 41 3279 DHCF device 
hex 42 ICF finance device 
hex 43 Retail communications device 
hex 44 3477-FA Display Station 
hex 45 3477-FC Display Station 
hex 46 3477-FD Display Station 
hex 47 3477-FW Display Station 
hex 48 3477-FE Display Station 
hex 4D Network Virtual Terminal display station 
hex 51 5555-C01 Display Station 
hex 52 5555-F01 Display Station 
hex 56 3476-EC Display Station 
hex 58 5555-G01 Display Station 
hex 59 5555-G02 Display Station 
hex 5D 3486-BA Display Station 
hex 5E  3486-BG Display Station 
hex 5F 3487-HE Display Station 
hex 60 3487-HD Display Station 
hex 61 3487-HW Display Station 
hex 62 3487-HC Display Station 
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Table C-3 (Page 3 of 3). Common I/O Feedback Area 


Data 

Offset Type Length Contents 

32 Character 10 Device name. For displays, the name of the device for which the operation just 
completed. 

42 Binary 4 Length of the record processed by the last I/O operation. 

46 Character 80 Reserved. 

126 Binary 2 Number of records retrieved on a read request for blocked records or sent on a 
write or force-end-of-data or force-end-of-volume request for blocked records. 

128 Binary 2 For output, the field value is the record format length, including first-character 
forms control, option indicators, source sequence numbers, and program-to- 
system data. If the value is zero, use the field at offset 42. 
For input, the field value is the record format length, including response indica- 
tors and source sequence numbers. If the value is zero, use the field at offset 
42. 

130 Character Reserved. 

132 Binary 4 Not applicable to displays. 

136 Character Reserved. 
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I/O Feedback Area for Display 


Files 


Table C-4 (Page 1 of 3). I/O Feedback Area for Display Files 


Data 
Offset Type Length Contents 
0 Character 2 Flag bits. 
Bit 1: Cancel-read indicator. 
0 The cancel-read operation did not cancel the read request. 
1 The cancel-read operation canceled the read request. 
Bit 2: Data-returned indicator. 
0 The cancel-read operation did not change the contents of the 
input buffer. 
1 The cancel-read operation placed the data from the read-with- 
no-wait operation into the input buffer. 
Bit 3: Command key indicator. 
0 Conditions for setting this indicator did not occur. 
1 The Print, Help, Home, Roll Up, Roll Down, or Clear key was 
pressed. The key is enabled with a DDS keyword, but without a 
response indicator specified. 
Bits 4-16: Reserved. 
2 Character 1 Attention indicator byte (AID). This field identifies which function key was 


pressed. This field will always contain the value hex F1 to imitate the Enter key 
being pressed on a display device. For display files, this field will contain the 
1-byte hexadecimal value returned from the device. 


Hex Codes’ Function Keys 


hex 31 1 
hex 32 2 
hex 33 3 
hex 34 4 
hex 35 5 
hex 36 6 
hex 37 7 
hex 38 8 
hex 39 9 
hex 3A 10 
hex 3B 11 
hex 3C 12 
hex B1 13 
hex B2 14 
hex B3 15 
hex B4 16 
hex B5 17 
hex B6 18 
hex B7 19 
hex B8& 20 
hex B9 21 
hex BA 22 
hex BB 23 
hex BC 24 
hex BD Clear 
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Table C-4 (Page 2 of 3). I/O Feedback Area for Display Files 


Offset 


Data 
Type 


Length 


Contents 


11 


13 


15 


17 
34 


36 


38 
46 
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Character 


Binary 


Binary 


Binary 


Binary 


Character 


Character 


Character 


Character 


Character 


Character 


17 


hex F1 Enter/Rec Adv 

hex F3 Help (not in operator-error mode) 

hex F4 Roll Down 

hex F5 Roll Up 

hex F6 Print 

hex F8 Record Backspace 

hex 3F Automatic Enter (for Selector Light Pen) 


Cursor location (line and position). Updated on input operations that are not 
subfile operations that return data to the program. For example, hex 0102 
means line 1, position 2. Line 10, position 33 would be hex 0A21. 


Actual data length. The length of the record format processed by the I/O opera- 
tion. 


Relative record number of a subfile record. Updated for a subfile record opera- 
tion. For input operations, updated only if data is returned to the program. If 
multiple subfiles are on the display, this offset will contain the relative record 
number for the last subfile updated. 


Indicates the lowest subfile relative record number currently displayed in the 
uppermost subfile display area if the last write operation was done to the subfile 
control record with SFLDSP specified. Updated for roll up and roll down oper- 
ations. Reset to 0 on a write operation to another record. Not set for message 
subfiles. 


Total number of records in a subfile. Updated on a put-relative operation to any 
subfile record. The number is set to zero on a write or write-read operation to 
any subfile control record with the SFLINZ keyword optioned on. If records are 
put to multiple subfiles on the display, this offset will contain the total number of 
records for all subfiles assuming that no write or write-read operations were per- 
formed to any subfile control record with the SFLINZ keyword optioned on. 


Cursor location relative to active DDS WINDOW keyword (line and position). 

Updated on input operations that are not subfile operations that return data to 
the program. The cursor location is based off the usable positions within the 
window. For example, hex 0C13 means line 12, position 19. 


Reserved. 
Major return code. 


00 Operation completed successfully. 

02 Input operation completed successfully, but job is being canceled 
(controlled). 

03 Input operation completed successfully, but no data received. 

04 Output exception. 

08 Device already acquired. 

11 Read from invited devices was not successful. 

34 Input exception. 

80 Permanent system or file error. 

81 Permanent session or device error. 

82 Acquire or open operation failed. 

83 Recoverable session or device error. 


Minor return code. For the values for a display file, see Appendix E, “Display 
File Return Codes” on page E-1. 


Not applicable to displays. 
Not applicable to displays. 
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Table C-4 (Page 3 of 3). I/O Feedback Area for Display Files 


Data 
Offset Type Length Contents 
47 Character 1 Reserved. 
48 Character 1 Not applicable to displays. 
49 Character 10 Not applicable to displays. 
59 Character 4 Reserved. 
63 Character Not applicable to displays. 
71 Character Reserved. 
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Get Attributes 


Performing the get attributes operation allows you 
to obtain certain information about a specific 
display device. 


Table C-5 (Page 1 of 3). Get Attributes 


Data 
Offset Type Length Contents 
0 Character 10 Program device name. 
10 Character 10 Device description name. Name of the device description associated with this 
entry. 
20 Character 10 User ID. 
30 Character 1 Device class. For displays, the device class is D. 
31 Character 6 Device type: 


3179 3179 Display Station 
317902 3179-2 Display Station 
3180 3180 Display Station 
3196A 3196-A1/A2 Display Station 
3196B 3196-B1/B2 Display Station 
3197C1 3197-C1 Display Station 
3197C2 3197-C2 Display Station 
3197D1  3197-D1 Display Station 
3197D2 3197-D2 Display Station 
3197W1 3197-W1 Display Station 
3197W2 3197-W2 Display Station 
3270 3270 Display Station 
3476EA 3476-EA Display Station 
3476-EC 3476-EC Display Station 
3477FA 3477-FA Display Station 
3477FC  3477-FC Display Station 
3477FD 3477-FD Display Station 
3477FE 3477-FE Display Station 
3477FG  3477-FG Display Station 
3477FW 3477-FW Display Station 
525111 5251 Display Station 
5291 5291 Display Station 
5292 5292 Display Station 
529202 5292-2 Display Station 
5555B1 5555-B01 Display Station 
5555C1 5555-C1 Display Station 
5555E1 5555-E01 Display Station 
5555F1 5555-F1 Display Station 
5555-G1 5555-G01 Display Station 
5555-G2 5555-G02 Display Station 
3486BA  3486-BA Display Station 
3486BG 3486-BG Display Station 
3487HC  3487-HC Display Station 
3487HD 3487-HD Display Station 
3487HE 3487-HE Display Station 
3487HW 3487-HW Display Station 
DHCF77 3277 DHCF device 
DHCF78 3278 DHCF device 
DHCF79 3279 DHCF device 
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Table C-5 (Page 2 of 3). Get Attributes 


Data 
Offset Type Length Contents 
37 Character 1 Requesting program device. This flag indicates whether this entry is defining a 
“REQUESTER device. 
N Not a *REQUESTER device (communications source device). 
Y A *REQUESTER device (communications target device). 
38 Character 1 Acquire status. Set even if device is implicitly acquired at open time. 
N Device is not acquired. 
Y Device is acquired. 
39 Character 1 Invite status. 
Y Device is invited. 
N Device is not invited. 
40 Character 1 Data available. 
Y Invited data is available. 
N Invited data is not available. 
41 Binary 2 Number of rows on display. 
43 Binary 2 Number of columns on display. 
45 Character 1 Display allow blink. 
Y Display is capable of blinking. 
N Display is not capable of blinking. 
46 Character 1 Online/offline status. 
O Display is online. 
F Display is offline. 
47 Character 1 Display location. 
L Local display. 
R Remote display. 
48 Character 1 Display type. 
A Alphanumeric or Katakana. 
| DBCS. 
49 Character 1 Keyboard type of display. 
A Alphanumeric or Katakana keyboard. 
| DBCS keyboard. 
50 Character 1 Not applicable to displays. 
51 Character 1 Not applicable to displays. 
52 Character 1 Not applicable to displays. 
53 Character 8 Not applicable to displays. 
61 Character 8 Not applicable to displays. 
69 Character 8 Not applicable to displays. 
77 Character 8 Not applicable to displays. 
85 Character 8 Not applicable to displays. 
93 Character 8 Not applicable to displays. 
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Table C-5 (Page 3 of 3). Get Attributes 


Data 
Offset Type Length Contents 
101 Character 1 Controller information. 
N Display is not attached to a controller that supports an enhanced 
interface for nonprogrammable work stations. 
1 Display is attached to a controller (type 1) 1 that supports an 
enhanced interface for nonprogrammable work stations. 
2 Display is attached to a controller (type 2) ' that supports an 
enhanced interface for nonprogrammable work stations. 
3 Display is attached to a controller (type 3) ' that supports an 
enhanced interface for nonprogrammable work stations. 
102 Character 1 Color capability of display. 
Y Color display 
N Monochrome display 
103 Character 1 Grid line support by display. 
Y Display supports grid lines 
N Display does not support grid lines 
104 Character 1 Not applicable to displays. 
105 Character 8 Not applicable to displays. 
113 Character 31 Reserved. 
1 
Type 1 Controllers available at V2R2 which support such things as windows, selection fields, scroll bars, and continued cursor 
progression. 
Type 2. = Controllers available at V2R3. These support all of the V2R2 functions as well as menu bars, continued-entry fields, 
edit masks, and simple hotspots. 
Type 3. Controllers available at V3R1. These support all of the V2R2 and V2R3 functions. They also support text in the bottom 


border of windows. 


C-14 Application Display Programming V4R1 


Appendix D. Double-Byte Character Set Support for Displays 


This appendix contains information that you need 
if you use double-byte characters. This includes 
the following topics: 


¢ Double-byte character set (DBCS) fundamen- 
tals 

e Processing double-byte characters 

e Device file support 

e Display support 

¢ Writing application programs that process 
double-byte characters 

¢ DBCS font tables 

¢ DBCS sort tables 

¢ DBCS conversion dictionaries 

e Using DBCS conversion 


DBCS printer and spooling support information 
can be found in the Printer Device Programming 
book. 


Double-Byte Character Set 
Fundamentals 


Some languages, such as Chinese, Japanese, 
and Korean, have a writing scheme that uses 
many different characters that cannot be repre- 
sented with single-byte codes. To create coded 
character sets for such languages, the system 
uses two bytes to represent each character. 
Characters that are encoded in two-byte code are 
called double-byte characters. 


The following example shows alphanumeric char- 
acters coded in a single-byte code scheme and 
double-byte characters coded in a double-byte 
code scheme. 


1-Byte Code 2-Byte Code 
(SBCS) (DBCS) 

A —— xc¢r A — X’42C1’ 

B — x’'Cc2’ B  — x’42C2’ 

1 — XFIT’ 1 — X’42F1’ 

2 — X'F2’ 2 — xX’42F2’ 
& — X’4481’ 
3x =—— x’457D’ (Japanese ) 
7s + =——  X’8877' (Japanese ) 
= =—— X'525F’ (Korean) 
it ——  x’4F99’ (Simplified Chinese ) 
#£ —  x’5B70’ (Traditional Chinese ) 


X’hhhh’ indicates that the code has the hexadecimal value, "hhhh". 


1-Byte Codes: |256 characters 


2-Byte Codes: |256 X 256 characters 


You can use double-byte characters as well as 
single-byte characters in one application. For 
instance, you may want to store double-byte data 
and single-byte data in your database, create your 
displays with double-byte text and fields, or print 
reports with double-byte characters. 
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DBCS Code Scheme 


IBM supports two DBCS code schemes: one for 
the host system, the other for personal computers. 
The IBM host-system code scheme has the fol- 
lowing code-range characteristics: 


First byte hex 41 to hex FE 
Second byte hex 41 to hex FE 
Double-byte blank hex 4040 


In the following figure, using the first byte as the 
vertical axis and the second byte as the horizontal 


D-1 


axis, 256 x 256 intersections (code points) are 
expressed. The lower-right code area is desig- 
nated as the valid double-byte code area and x is 
assigned to the double-byte blank. 


2nd byte —————> 


ist 0 4/4 FF 
byte 0 0|1 EF 

00 

40 x 

41 

D 
FE 
FF 


D: double-byte code area 


x: double-byte blank RSLH712-4 


Figure D-1. IBM Host-System Code Scheme 


By assigning the values hex 41 to hex FE in the 
first and second bytes as the DBCS character 
codes, the codes can be grouped in wards with 
192 code points in each ward. For example, the 
code group with the first byte starting with hex 42 
is called ward 42. Ward 42 has the same alpha- 
numeric characters as those in a corresponding 
single-byte EBCDIC code page, but with double- 
byte codes. For example, the character A is 
represented in single-byte EBCDIC code as hex 
C1 and in IBM-host code as hex 42C1. 


The AS/400 system supports the following double- 
byte character sets: 


e IBM Japanese 

e IBM Korean 

¢ IBM Simplified Chinese 
e IBM Traditional Chinese 


The following tables show the code ranges for 
each character set and the number of characters 
supported in each character set. 


Table D-1. IBM Japanese Character Set 


Number of 
Wards Content Characters 
40 Space in 4040 1 
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Table D-1. IBM Japanese Character Set 


Number of 


Wards Content Characters 


41 to 44 Non-Kanji characters 549 


¢ Greek, Russian, 
Roman numeric 
(ward 41) 
e Alphanumeric and 
related symbols 
(ward 42) 
e Katakana, 
Hiragana, and 
special symbols 
(ward 43-44) 
Basic Kanji characters 3226 
Extended Kanji charac- 3487 
ters 
69 to 7F User-defined characters 
80 to FE Reserved 
Total number of IBM-defined characters: 7263 


45 to 55 
56 to 68 


Up to 4370 


Table D-2. IBM Korean Character Set 


Number of 
Wards Content Characters 
40 Space in 4040 1 
41 to 46 Non-Hangeul/Hanja 939 
characters (Latin 
alphabet, Greek, 
Roman, Japanese 
Kana, numeric, special 
symbols) 
47 to 4F Reserved 
50 to 6C Hanja characters 5265 
6D to 83 Reserved 
84 to D3 Hangeul characters 2672 
(Jamo included) 
D4 to DD User-defined characters Up to 1880 
DE to FE Reserved 


Total number of IBM-defined characters: 8877 


Table D-3. IBM Simplified Chinese Character Set 


Number of 

Wards Content Characters 
40 Space in 4040 1 
41 to 47 Non-Chinese charac- 712 

ters (Latin alphabet, 

Greek, Russian, 

Japanese Kana, 

numeric, special 

symbols) 
48 to 6F Chinese characters: 3755 and 

Level 1 and Level 2 3008 
70 to 75 Reserved 
76 to 7F User-defined characters Up to 1880 
80 to FE Reserved 


Total number of IBM-defined characters: 7476 


Table D-4. IBM Traditional Chinese Character Set 


Number of 
Wards Content Characters 
40 Space in 4040 1 
41 to 46 Non-Chinese charac- 674 
ters (Latin alphabet, 
Greek, Roman, 
Japanese Kana, 
numeric, special 
symbols) 
47 to 4B Reserved 
AC to 68 Primary Chinese char- 5401 
acters 
69 to 91 Secondary Chinese 7652 
characters 
92 to CF Reserved 
DO to DD User-defined characters Up to 2632 
DE to FE Reserved 


Total number of IBM-defined characters: 13728 


This code scheme applies to the AS/400 system, 
System/36, System/38, as well as the 
System/370* system. A different DBCS code 
scheme, called the IBM personal computer DBCS 
code scheme, is used on the Personal System/55. 
For details of the IBM personal computer DBCS 
code scheme, refer to IBM PS/55 publications. 


Double-byte code that is not valid has a double- 
byte code value that is not in the valid double-byte 
code range. Double-byte code that is not valid is 
not the same as undefined double-byte code, 
which has valid double-byte code value but no 
graphic symbol currently defined for the code. 


Shift-Control Characters 


When the IBM host-system code scheme is used, 
the system uses shift-control characters to identify 
the beginning and end of a string of double-byte 
characters. The shift-out (SO) character, hex OE, 
indicates the beginning of a double-byte character 
string. The shift-in (SI) character, hex OF, indi- 
cates the end of a double-byte character string. 


1-Byte Data 1-Byte Data 
2-Byte Data 
1-Byte Data SO | 2-Byte Data SI | 1-Byte Data 


Control 


Character 
RSLH713-1 


Each shift-control character occupies the same 
amount of space as one alphanumeric character. 
By contrast, double-byte characters occupy the 
same amount of space as two alphanumeric char- 
acters. 


Using Double-Byte Data 


This section tells you how you can use double- 
byte data and discusses the limitations to its use. 


How You Can Use: You can use double- 
byte data in the following ways: 


e As data in files: 


— Data entered in input-capable fields and 
data displayed in output-capable fields of 
display files. 

— Data used as literals in display files. 


e As the text of messages. 
¢ As the text of object descriptions. 


e As literals and constants, and as data to be 
processed by high-level language programs. 


e As search words when using the information 
search function. For more information on 
DBCS and the search information function, 
see “National Language Considerations” on 
page 20-12. 


Double-byte data can be displayed only at DBCS 
display stations. Double-byte data can be written 
onto diskettes and tape, as well as onto disk 
storage. 
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How You Cannot Use: You cannot use 
double-byte data in the following ways: 


¢ As AS/400 object names. 

e As command names or variable names in 
control language (CL) and other high-level lan- 
guages. 

e As displayed output on alphanumeric display 
stations. 


Double-Byte Character Size 


When displayed, double-byte characters are twice 
as wide as alphanumeric characters. 


Consider the width of double-byte characters 
when you calculate the length of a double-byte 
data field because field lengths are usually identi- 
fied as the number of alphanumeric character 
positions used. For more information on calcu- 
lating the length of fields containing double-byte 
data, refer to the DDS Reference. 


Processing Double-Byte 
Characters 


Due to the large number of double-byte charac- 
ters, the system needs more information to identify 
each double-byte character than is needed to 
identify each alphanumeric character. 


There are two types of double-byte characters: 
basic and extended. These characters are usually 
processed by the display station on which the 
characters are displayed. 


Basic Characters 


A DBCS display station can process basic charac- 
ters without any assistance from the system. The 
display station knows about the graphic characters 
because they are stored in the display station. 
The number of double-byte characters that are 
stored in the display station varies with the lan- 
guage supported and the storage size of the 
display station. A DBCS display station can 
display basic characters without using the 
extended character processing function of the 
operating system. 
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Extended Characters 


When processing extended characters, the display 
station requires the assistance of the system. The 
system must tell the display station what the char- 
acter looks like before the display station can 
display the character. Extended characters are 
stored in a DBCS font table, not in the DBCS 
display station. When displaying extended char- 
acters, the display station receives them from the 
DBCS font table under control of the operating 
system. 


Extended character processing is a function of the 
operating system that is required to make charac- 
ters stored in a DBCS font table available to a 
DBCS display station. 


To request extended character processing, specify 
the double-byte extended character parameter, 
IGCEXNCHR(*YES), on the file creation command 
when you create a display (CRTDSPF command) 
file that processes double-byte data. Because 
IGCEXNCHR(*YES) is the default value, the 
system automatically processes extended charac- 
ters unless you instruct it otherwise. You can 
change this file attribute by using a change file 
(CHGDSPF) or override file (OVRDSPF) 
command. For example, to override the display 
file DBCSDSPF so that extended characters are 
processed, enter: 


OVRDSPF DSPF(DBCSDSPF) IGCEXNCHR(*YES) 


Note: The system ignores the IGCEXNCHR 
parameter when processing alphanumeric files. 


What Happens When Extended 
Characters Are Not Processed 


When extended characters are not processed, the 
following happens: 


e Basic characters are displayed. 

e¢ The system displays the undefined character 
where it would otherwise display extended 
characters. 

e The extended characters, though not dis- 
played, are stored correctly in the system. 


Device File Support 


The following sections describe DBCS device files 
and special considerations for working with DBCS 
device files. Data description specifications (DDS) 
can be used with DBCS device files. For informa- 
tion about using DDS, refer to the DDS 
Reference. 


What a DBCS File Is 


A DBCS file is a file that contains double-byte 
data or is used to process double-byte data. 
Other files are called alohanumeric files. 


Display files can be DBCS files. 


When to Indicate a DBCS File 


You should indicate that a file is DBCS in one or 
more of the following situations: 


e The file receives input, or displays output, 
which has double-byte characters. 

e The file contains double-byte literals. 

¢ The file has double-byte literals in the DDS 
that are used in the file at processing time 
(such as constant fields and error messages). 

¢ The DDS of the file includes DBCS keywords. 
See the DDS Reference for information on 
these keywords. 

¢ The file stores double-byte data (database 
files). 


How to Indicate a DBCS File 


You must indicate that a device file is a DBCS file 
in order for the system to process double-byte 
data properly. You can do this in one of the fol- 
lowing ways: 
¢ By specifying IGCDTA(*YES) on the Create 
Display File (CRTDSPF) command 


e¢ Through DDS 


DDS provides fields of the following data types: 


DBCS-Only Field 
DBCS-only fields display and accept only 
double-byte characters. Double-byte charac- 
ters are always enclosed in shift-out and 
shift-in characters that have to be paired. 


DBCS-Open Field 
DBCS-open fields display and accept both 
single-byte and double-byte characters. 
Double-byte characters are enclosed in 
shift-out and shift-in characters that have to 
be paired. 


DBCS-Either Field 
DBCS-either fields display and accept either 
single-byte or double-byte characters, but not 
both. Double-byte characters are enclosed in 
shift-out and shift-in character pairs. 


DBCS-Graphic Field 
DBCS-graphic fields do not contain shift-out 
and shift-in characters. 


In display files, you can define fields with 
DBCS-only data type (type J), either data type 
(type E), open data type (type O), or 
DBCS-graphic data type (type G). 


You can also use a double-byte literal that is used 
with the file at processing time, such as literals 
specified with the Default (DFT) and Error 
Message (ERRMSG) DDS keywords. 


Note: You may also use double-byte literals as 
text and comments in a file, such as with the DDS 
keyword TEXT. However, the system does not 
consider a file, whose only DBCS attribute is that 
it has double-byte comments, to be a DBCS file. 


You may also specify the Alternative Data Type 
(IGCALTTYP) DDS keyword in display files. This 
keyword lets you use display files with both alpha- 
numeric and double-byte applications. When you 
put the IGCALTTYP keyword into effect, you can 
use double-byte data with the file. 


Put the IGCALTTYP keyword into effect by cre- 
ating, changing, or overriding display files with the 
IGCDTA(*YES) value. You can put the 
IGCALTTYP keyword into effect for display files by 
specifying IGCDTA(*YES) on the following device 
file commands: 


¢ Create Display File (CRTDSPF) 
¢ Change Display File (CHGDSPF) 
¢ Override with Display File (OVRDSPF) 


When you specify IGCDTA(*NO), the IGCALTTYP 
keyword is not in effect and you can use only 
alphanumeric data with the file. Changing or over- 
riding the file to put the IGCALTTYP keyword into 
effect does not change the DDS of the file. 
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Except when using the IGCALTTYP function, you 
do not need to specify IGCDTA(*YES) on the file 
creation command if you have already specified 
DBCS functions in the DDS. Instead, specify 
IGCDTA(*YES) when the file has DBCS functions 
that are not indicated in the DDS. For example, 
specify IGCDTA(*YES) on the file creation 
command if the file is intended to contain double- 
byte data. 


Improperly Indicated DBCS Files 


If you do not properly indicate that a display file is 
a DBCS file, one of the following happens: 


¢ Display data management assumes that the 
output data to the display does not contain 
double-byte data. The end result depends on 
whether the display is an alphanumeric or 
DBCS display. 


If the display is an alphanumeric display, the 
double-byte data is interpreted as alphanu- 
meric data. The shift-control characters 
appear as blanks. The displayed double-byte 
data does not make sense. 


If the display is a DBCS display, the double- 
byte data is displayed with the exception of 
extended characters. The system does not 
perform extended character processing on the 
data. Therefore, extended characters are dis- 
played with the symbol for undefined double- 
byte characters. 


e The system does not recognize literals with 
DBCS text as double-byte literals if the source 
file is not specified as a DBCS file. 


Display Support 


The following sections describe information on dis- 
playing double-byte characters. 


Inserting Shift-Control Characters 


The system inserts shift-control characters into 
DBCS-only fields automatically. 


To insert shift-control characters into DBCS-open 
fields or DBCS-either fields, do the following: 
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1. Position the cursor in the field in which you 
want to insert double-byte data. 

2. Press the Insert Shift Control Character key 
(according to your DBCS display station user's 
guide). 


The system inserts a pair of shift-control charac- 
ters at the same time, as follows (where 0; repre- 
sents the shift-out character and 0, represents the 
shift-in character): 


0-0¢ 


The system leaves the cursor under the shift-in 
character and puts the keyboard in insert mode. 
Insert double-byte characters between the shift- 
control characters. To insert double-byte charac- 
ters, start typing in double-byte characters at the 
cursor position. For example, enter the double- 
byte character string D1D2D3, as follows (where 
O- represents the shift-out character, O- repre- 
sents the shift-in character, and D1, D2, and D3 
represent three double-byte characters): 


0-D1D2D30, 


To find out if a field already has the shift-control 
characters, press the Display Shift Control Char- 
acter key. 


Number of Displayed Extended 
Characters 


The system can display up to 512 different 
extended characters on a Japanese display at one 
time. Additional extended characters are dis- 
played as undefined characters. However, the 
additional extended characters are stored correctly 
in the system. 


Number of Input Fields on a 
Display 


The use of DBCS input fields affects the total 
number of input fields allowed on a display. Fora 
5250 display station, you can specify as many as 
256 input fields. However, each three instances 
of a DBCS field reduces the maximum number of 
fields by one. For example, if there are 9 DBCS 
fields on a display, then the maximum is 
256-(9/3)=253 input fields. 


Effects of Displaying Double-Byte 
Data at Alphanumeric Work 
Stations 


Alphanumeric display stations cannot display 
double-byte data correctly. If you try to display 
double-byte data at an alphanumeric display 
station, the following happens: 


e The system sends an inquiry message to that 
display station, asking whether you want to 
continue using the program with double-byte 
data or to cancel it. 


e If you continue using the program, the system 
ignores the shift-control characters and inter- 
prets the double-byte characters as though 
they were alphanumeric. Displayed double- 
byte data does not make sense. 


Effects of Displaying 
DBCS-Graphic Fields on 
Double-Byte Displays 


The following occurs when displaying 
DBCS-graphic fields on a DBCS-graphic display 
without graphic capabilities. 


e lf aDBCS-graphic field is sent to a DBCS 
device without graphic capabilities, shift 
control characters are added to the field and 
one DBCS character is truncated from the end 
of the field. For example, assume an output 
buffer contained the graphic characters 
‘ABCD’, and also assume the characters are 
displayed on a device without graphic capabili- 
ties. When the characters are displayed, they 
appear as 'ABC' with shift control characters 
at the beginning and end of the field. 


e lf the program is displaying an output 
DBCS-graphic field one character long, the 
field is displayed with 2 null characters. This 
is because a DBCS field needs to be defined 
at least 4 bytes long to allow room for the shift 
control characters and a DBCS character. 


e If the program is displaying an input 
DBCS-graphic field 1 character long, message 
CPF501F will be sent to the calling program. 
The message explains that an incorrect field 
length caused the output operation to fail. 
Ensure that DBCS input capable fields sent to 
the DBCS device are at least 4 bytes long. 


Application Program 
Considerations 


The following sections describe considerations for 
writing applications that process double-byte data. 


Designing Application Programs 
That Process Double-Byte Data 


Design your application programs for processing 
double-byte data in the same way you design 
application programs for processing alphanumeric 
data, with the following additional considerations: 


¢ Design display formats that can be used with 
double-byte data. 


e If needed, provide DBCS conversion as a 
means of entering double-byte data for inter- 
active applications. Use the DDS keyword for 
DBCS conversion (IGCCNV) to specify DBCS 
conversion in display files. Because DBCS 
display stations provide a variety of double- 
byte data entry methods, you are not required 
to use the AS/400 DBCS conversion function 
to enter double-byte data. 


¢ Create double-byte messages to be used by 
the program. 


e Specify extended character processing so that 
the system displays all double-byte data. See 
“Extended Characters” on page D-4 for 
instructions. 


¢ Determine whether additional double-byte 
characters need to be defined. User-defined 
characters can be defined and maintained 
using the character generator utility (CGU). 
Information on CGU can be found in the 
ADTS/400: Character Generator Utility book. 


e Make sure that the double-byte data is always 
processed in a double-byte unit and do not 
split a double-byte character. 


Double-byte characters displayed on a DBCS 
display that are located at the end of the 
column and that do not allow room for the 
shift-out character, are not included in the 
print of the display. This is because shift 
characters have to be matched for each 
printed line when the print key is pressed. 
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Changing Alphanumeric 
Application Programs to DBCS 
Application Programs 


If an alphanumeric application program uses 
externally described files, you can change that 
application program to a DBCS application 
program by changing the externally described 
files. To convert an application program, do the 
following: 


1. Create a duplicate copy of the source state- 
ments for the alphanumeric file that you want 
to change. 


2. Change alphanumeric constants and literals to 
double-byte constants and literals. 


3. Change fields in the file to the open (O) data 
type or specify the Alternative Data Type 
(IGCALTTYP) DDS keyword so that you can 
enter both double-byte and alphanumeric data 
in these fields. You may want to change the 
length of the fields as the double-byte data 
takes more space. 


4. Store the converted file in a separate library. 
Give the file the same name as its alphanu- 
meric version. 


5. When you want to use the changed file in a 
job, change the library list, using the Change 
Library List (CHGLIBL) command, for the job 
in which the file will be used. The library in 
which the DBCS display file is stored is then 
checked before the library in which the alpha- 
numeric version of the file is stored. 


DBCS Font Tables 


DBCS font tables contain the images of the 
double-byte extended characters used on the 
system. The system uses these images to display 
and print extended characters. 


The following DBCS font tables are objects that 
you can save or restore. These font tables are 
distributed with the DBCS national language ver- 
sions of the OS/400 licensed program: 


QIGC2424 A Japanese DBCS font table used to 
display and print extended charac- 
ters in a 24-by-24 dot matrix image. 
The system uses the table with 
Japanese display stations, printers 
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attached to display stations, 5227 
Model 1 Printer, and the 5327 Model 
1 Printer. 


QIGC2424C A Traditional Chinese DBCS font 
table used to print extended charac- 
ters in a 24-by-24 dot matrix image. 
The system uses the table with the 
5227 Model 3 Printer and the 5327 
Model 3 Printer. 


QIGC2424K A Korean DBCS font table used to 
print extended characters in a 
24-by-24 dot matrix image. The 
system uses the table with the 5227 
Model 2 Printer and the 5327 Model 
2 Printer. 


QIGC2424S A Simplified Chinese DBCS font 
table used to print extended charac- 
ters in a 24-by-24 dot matrix image. 
The system uses the table with the 
5227 Model 5 Printer. 


A Japanese DBCS font table used to 
print characters in a 32-by-32 dot 
matrix image. The system uses the 
table with the 5583 Printer and the 
5337 Model 1 Printer. 


QIGC3232S A Simplified Chinese DBCS font 
table used to print characters in a 
32-by-32 dot matrix image. The 
system uses the table with the 5337 
Model RO5 Printer. 


QIGC3232 


All DBCS font tables have an object type of 
*“ICGTBL. You can find instructions for adding 
user-defined characters to DBCS font tables in the 
the ADTS/400: Character Generator Utility book. 


Finding Out if a DBCS Font Table 
Exists 


Use the Check DBCS Font Table (CHKIGCTBL) 
command to find out if a DBCS font table exists in 
your system. 


For example, to find out if the table QIGC2424 
exists, enter: 


CHKIGCTBL IGCTBL(Q1IGC2424) 
If the table does not exist, the system responds 


with a message. If the table does exist, the 
system simply returns without a message. 


Check for the existence of a table when adding a 
new type of DBCS display station to make sure 
that the table used by the device exists in the 
system. 


Copying a DBCS Font Table onto 
Tape or Diskette 


Use the Copy DBCS Font Table (CPYIGCTBL) 
command to copy a DBCS font table onto tape or 
diskette. 


Copy a DBCS font table onto tape or diskette in 
the following instances: 


¢ Before deleting that table. 

e After new user-defined characters are added 
to the tables. 

e When planning to use the tables on another 
system. 


The DBCS font tables are saved when you use 
the Save System (SAVSYS) command so you do 
not have to use the CPYIGCTBL command when 
performing normal system backup. 


How to Copy a Table onto Tape or 


Diskette: To copy a DBCS font table onto a 
tape or diskettes, do the following: 


1. Make sure that you have a tape or diskettes 
initialized to the *DATA format. If necessary, 
specify the FMT(*DATA) parameter on the Ini- 
tialize Diskette (INZDKT) command to letOthe 
system prepare the tape or diskettes. 


2. Load the initialized tape or diskette onto the 
system. 


3. Enter the CPYIGCTBL command as follows: 


a. Choose the value OPTION(*OUT). 

b. Use the DEV parameter to select the 
device to which you want to copy the 
table. 

c. Use the SELECT and RANGE parameters 
to specify which portion of the table you 
want copied from the system. See the 
description of the CPYIGCTBL command 
in the CL Reference for instructions on 
choosing SELECT and RANGE parameter 
values. 


The following are two examples of the 
CPYIGCTBL command used to copy a DBCS 
font table to removable media. 


¢ To copy the DBCS font table QIGC2424 
onto diskettes, enter: 


CPYIGCTBL IGCTBL(QIGC2424) OPTION(*OUT) DEV(QDKT) 


¢ To copy just the user-defined characters 
from DBCS font table QIGC2424 onto 
tape, enter: 


CPYIGCTBL IGCTBL(QIGC2424) OPTION(*OUT) 
DEV(QTAPQ1) SELECT (*USER) 


4. Press the Enter key. The system copies the 
DBCS font table onto the specified media. 


5. Remove the tape or diskette after the system 
finishes copying the table. 


Copying a DBCS Font Table from 
Tape or Diskette 


Use the Copy DBCS Font Table (CPYIGCTBL) 
command to copy a DBCS font table from a tape 
or a diskette onto the system. The system auto- 
matically creates the DBCS font table again when 
copying its contents if the following are true: 


e The specified table does not already exist in 
the system. 

e The media from which you are copying the 
table contains all of the IBM-defined double- 
byte characters. 

e SELECT(*ALL) or SELECT(*SYS) is specified 
on the CPYIGCTBL command. 


How to Copy a Table from a Tape or 


Diskette: To copy a DBCS font table from tape 
or diskette onto the system: 


1. Load the removable media from which the 
table will be copied onto the system. 
2. Enter the CPYIGCTBL command as follows: 

a. Choose the OPTION(*IN) value. 

b. Use the DEV parameter to select the 
device from which to copy the DBCS font 
table. 

c. Use the SELECT and RANGE parameters 
to specify which portion of the table will be 
copied from the tape or diskette. See the 
CL Reference for a description of the 
CPYIGCTBL command and for 
instructions on choosing SELECT and 
RANGE parameter values. 

The following are two examples of commands 
used to copy a DBCS font table to the system. 
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¢ To copy the DBCS font table QIGC2424 
from diskette, enter: 


CPYIGCTBL IGCTBL(QIGC2424) OPTION(*IN) 
DEV (QDKT) 


¢ To copy just the user-defined characters 
from DBCS font table QIGC2424 from 
tape and to replace the user-defined char- 
acters in the table with the ones from the 
tape, enter: 


CPYIGCTBL IGCTBL(QIGC2424) OPTION(*IN) 
DEV(QTAPQ1) SELECT(*USER) RPLIMG(*YES) 


3. Press the Enter key. The system copies the 
DBCS font table from the tape or diskette onto 
the system. 

4. Remove the tape or diskette after the system 
finishes copying the table. 


Deleting a DBCS Font Table 


Use the Delete DBCS Font Table (DLTIGCTBL) 
command to delete a DBCS font table from the 
system. 


Delete an unused DBCS font table to make more 
storage space available. For example, if you do 
not plan to use Japanese printer 5583 or 5337 
with your system, DBCS font table QIGC3232 is 
not needed and can be deleted. 


How to Delete a DBCS Font Table: To 
delete a table, do the following: 


1. If desired, copy the table onto tape or 
diskettes. See “Copying a DBCS Font Table 
onto Tape or Diskette” on page D-9 for 
instructions. If you do not copy the table to 
removable media before deleting it, you will 
not have a copy of the table for future use. 


2. Vary off all devices using that table. 
3. Enter the DLTIGCTBL command. 


For example, to delete the DBCS font table 
QIGC3232, enter: 


DLTIGCTBL IGCTBL(QIGC3232) 


4. Press the Enter key. The system sends 
inquiry message CPA8424 to the system 
operator message queue for you to confirm 
your intention to delete a DBCS font table. 


5. Respond to the inquiry message. The system 
sends you a message when it has deleted the 
table. 
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Warning: Do not delete a DBCS font table if any 
device using that table is currently varied on. 
Also, make sure that the affected controller is not 
varied on. If you try to delete the table while the 
device and controller are varied on, the system 
reports any devices attached to the same 
controller(s) as those devices, and the controller(s) 
as damaged the next time you try to print or 
display extended characters on an affected 
device. If such damage is reported, do the fol- 
lowing: 


1. Vary off the affected devices, using the Vary 
Configuration (VRYCFG) command. 

2. Vary off the affected controller. 

3. Vary on the affected controller. 

4. Vary on the affected devices. 

5. Continue normal work. 


Starting the Character Generator 
Utility 


You must use the character generator utility 
(CGU) to regenerate the font tables. Use the 
STRCGU command to start the character gener- 
ator utility. You may call the CGU main menu or 
specify a specific CGU function, depending on the 
parameter used. Refer to the ADTS/400: Char- 
acter Generator Utility book for more information. 


Copying User-Defined 
Double-Byte Characters 


Use the STRFMA command to copy user-defined 
double-byte characters between an AS/400 DBCS 
font table and a user font file at a Personal 
System/55, a 5295 Display Station, or an 
InfoWindow 3477 Display Station. 


DBCS Font Files 


In addition to the system-supplied DBCS font 
tables, the system also provides DBCS font files. 
These DBCS font files are physical files which 
contain frequently used double-byte characters. 
When using the character generator utility, you 
can use the characters in these files as the base 
for a new user-defined character. These files are 
supplied with read-only authority as they are not to 
be changed. If you do not use the character gen- 
erator utility or the Advanced DBCS Printer 


Support/400 licensed program, you may delete 
these files to save space. They all exist in the 
QSYS library. 


The following DBCS font files are distributed with 
the DBCS national language versions of the 
OS/400 licensed program. They are used as a 
reference for the CGU and the Advanced DBCS 
Printer Support/400 licensed program. 


QCGF2424 A Japanese DBCS font file used to 
store a copy of the Japanese DBCS 
basic character images. 


QCGF2424K A Korean DBCS font file used to 
store a copy of the Korean DBCS 
basic character images. 


QCGF2424C A Traditional Chinese DBCS font file 
used to store a copy of the Tradi- 
tional Chinese DBCS basic character 
images. 


QCGF2424S A Simplified Chinese DBCS font file 
used to store a copy of the Simpli- 
fied Chinese DBCS basic character 
images. 


DBCS Sort Tables 


DBCS sort tables contain the sort information and 
collating sequences of all the double-byte charac- 
ters used on the system. The system uses these 
tables to sort double-byte characters using the 
sort utility. 


DBCS sort tables are objects that you can save, 
restore, and delete. Using the character generator 
utility you can also add, delete, and change 
entries in these tables corresponding to the image 
entries in the DBCS font tables. For Japanese 
use only, you can also copy the DBCS master sort 
table to and from a data file. 


The following DBCS sort tables are distributed 
with the DBCS national language versions of the 
OS/400 licensed program: 


QCGMSTR A Japanese DBCS master sort table 
used to store the sort information for 
the Japanese double-byte character 
set. 


QCGACTV A Japanese DBCS active sort table 
used to store the sort collating 
sequences for the Japanese double- 
byte character set. 


QCGMSTRC A Traditional Chinese DBCS master 
sort table used to store the sort infor- 
mation for the Traditional Chinese 
double-byte character set. 


QCGACTVC A Traditional Chinese DBCS active 
sort table used to store the sort col- 
lating sequences for the Traditional 
Chinese double-byte character set. 


QCGACTVK A Korean DBCS active sort table 
used to map Hanja characters to 
Hangeul characters with equivalent 
pronunciation. 


QCGMSTRS A Simplified Chinese DBCS master 
sort table used to store the sort infor- 
mation for the Simplified Chinese 
double-byte character set. 


QCGACTVS A Simplified Chinese DBCS active 
sort table used to store the sort col- 
lating sequences for the Simplified 
Chinese double-byte character set. 


You may sort Japanese, Korean, Simplified 
Chinese, and Traditional Chinese double-byte 
characters. Each of these languages has two 
DBCS sort tables, a DBCS master sort table and 
a DBCS active sort table, except for Korean which 
has only a DBCS active sort table. The DBCS 
master sort table contains sort information for all 
defined DBCS characters. The DBCS active sort 
table for Japanese, Simplified Chinese, and Tradi- 
tional Chinese is created from the master sort 
table information and contains the collating 
sequences for the double-byte characters of that 
given language. These collating sequences have 
a purpose similar to the EBCDIC and ASCII col- 
lating sequences for the single-byte alphanumeric 
character set. For Korean characters, the 
Hangeul characters are assigned both their col- 
lating sequence as well as their DBCS codes 
according to their pronunciation. Hence, a sepa- 
rate collating sequence is not required, and each 
of the Hanja characters is mapped to a Hangeul 
character of the same pronunciation using the 
DBCS active sort table QCGACTVK. 


All DBCS sort tables have an object type of 
*“IGCSRT. 
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Using DBCS Sort Tables on the 
System 


You can save the tables to tape or diskette, delete 
them from the system, and restore them to the 
system. The Japanese DBCS master sort table 
can also be copied to a data file and copied from 
a data file so that it can be shared with a 
System/36 or Application System/Entry* (AS/Entry) 
system. You can also add sort information for 
each user-defined character, and add that char- 
acter to the DBCS collating sequence, as you 
create it using the character generator utility. 


Finding Out if a DBCS Sort Table 
Exists 


Use the Check Object (CHKOBJ) command to find 
out if a DBCS sort table exists in your system. 


For example, to find out if the table QCGMSTR 
exists, enter: 


CHKOBJ OBJ(QSYS/QCGMSTR) OBJTYPE(*IGCSRT) 


If the table does not exist, the system responds 
with a message. If the table does exist, the 
system simply returns without a message. 


Check for the existence of a DBCS active sort 
table when you want to sort double-byte charac- 
ters for the first time. The DBCS active table for 
the DBCS language must exist to sort the charac- 
ters. 


Saving a DBCS Sort Table onto 
Tape or Diskette 


Use the Save Object (SAVOBJ) command to save 
a DBCS sort table onto tape or diskette. Specify 
“IGCSRT for the object type. 


The DBCS sort tables are saved when you use 
the SAVSYS command so you do not have to use 
the SAVOBJ command when performing normal 
system backup. 
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When to Save a DBCS Sort Table onto 


Tape or Diskette: Save a DBCS sort table 
onto tape or diskette in the following instances: 


¢ Before deleting that table 

e After information is added, updated, or 
changed in the tables using the character gen- 
erator utility 

e When planning to use the tables on another 
AS/400 system 


Restoring a DBCS Sort Table 
from Tape or Diskette 


Use the RSTOBJ command to restore a DBCS 
sort table from a tape or a diskette onto the 
system. The tables on the tape or diskette must 
previously have been saved using the SAVOBJ 
command. Specify *IGCSRT for the object type. 
The system automatically re-creates the DBCS 
sort table when the specified table does not 
already exist in the system. 


These tables must be restored to the QSYS library 
for the system to know they exist. For that 
reason, RSTOB restores *IGCSRT objects only 
to the QSYS library and only if the objects do not 
already exist there. 


Copying a Japanese DBCS 
Master Sort Table to a Data File 


Through the character generator utility, use the 
CPYIGCSRT command to copy the Japanese 
DBCS master sort table (QOGMSTR) to a data 
file. This data file can then be moved to a 
System/36 system or AS/Entry system to replace 
the Japanese master sort table there. 


When to Copy the Japanese DBCS 


Master Sort Table to a Data File: Copy 
the Japanese DBCS master sort table to a data 
file in the following instances: 


e When planning to move the table to a 
System/36 or AS/Entry system for use there. 
You should always transport the Japanese 
DBCS master sort table together with the 
Japanese DBCS font tables. 


¢ Before deleting that table, as an alternative to 
the SAVOBJ command. You can then keep 
the file or save it on diskette or tape. 


How to Copy the Japanese DBCS 
Master Sort Table to a Data File 


Note: In this section, the AS/Entry system also 


applies to every instance of System/36.: To copy 
the Japanese DBCS master sort table to a data 
file, do the following: 


1. Decide what data file you want to copy it to. 
The file need not exist, it will be automatically 
created. 


2. Enter the CPYIGCSRT command as follows: 


a. Choose the value OPTION(*OUT). 

b. Use the FILE parameter to specify the 
name of the data file to which you want to 
copy the master table. If you are trans- 
porting the master table to the System/36 
for use there, you should specify a file 
name of #KAMAST, or you will have to 
rename the file when you get it to the 
System/36. Use the AS/400 CPYF 
command for copying the file onto 
diskette, and the System/36 TRANSFER 
command for copying the file from diskette 
to the System/36. 

c. Use the MBR parameter to specify the 
name of the data file member to which 
you want to copy the master table. If you 
are transporting the master table to the 
System/36 for use there, you should 
specify *FILE for the MBR parameter. 


3. Press the Enter key. The system creates the 
file and member if they do not exist, and 
writes over the existing member if it does 
exist. 


4. If you now transport this file to your System/36 
to replace the #KAMAST file there, you should 
also use the SRTXBLD procedure to update 
the active table to reflect the new master 
table. 


Copying a Japanese DBCS 
Master Sort Table from a Data 
File 

Use the CPYIGCSRT command to copy the 


Japanese DBCS master sort table (QQGMSTR) 
from a data file. 


When to Copy the Japanese DBCS 
Master Sort Table from a Data File: 


You may use the System/36 Migration Aid to 
migrate the System/36 or AS/Entry system master 
sort file (HKAMAST) to the AS/400 system. When 
you migrate the #KAMAST file using the 
System/36 Migration Aid, you do not have to use 
the CPYIGCSRT command. 


Copy the Japanese DBCS master sort table from 
a data file in the following instances: 


e When you do not use the System/36 Migration 
Aid, you may copy the #KAMAST file from the 
System/36 or AS/Entry system to the AS/400 
system. Then use the CPYIGCSRT command 
to copy sort information from the #KAMAST 
file to the AS/400 master sort table 
(QCGMSTR). Delete the #KAMAST file from 
the AS/400 system after you complete the 
copy operation. 


e When you have copied a version of the 
master table to a data file and you now want 
to restore that version. 


You should always migrate or copy the 
Japanese DBCS master sort table together 
with the Japanese DBCS font tables. 


How to Copy the Japanese DBCS 


Master Sort Table from a Data File: To 
copy the Japanese DBCS master sort table from a 
data file, do the following: 


1. Enter the CPYIGCSRT command as follows: 


a. Choose the value OPTION(*IN). 

b. Use the FILE parameter to specify the 
name of the data file that contains a 
migrated System/36 or AS/Entry system 
master file or an AS/400 master table pre- 
viously copied to the file using 
OPTION(*OUT) with the CPYIGCSRT 
command. To migrate your System/36 or 
AS/Entry system master file without using 
the System/36 Migration Aid, use the 
TRANSFER command with the IFORMAT 
parameter on the System/36 or AS/Entry 
system to save the #KAMAST masier file 
on diskette. Use the AS/400 Copy File 
(CPYF) command to copy the master file 
#KAMAST from diskette. Use the 
CPYIGCSRT command as described here 
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to copy data from the file to the AS/400 
Japanese DBCS masier sort table. 

c. Use the MBR parameter to specify the 
name of the data file member from which 
you want to copy the master table data. 


2. Press the Enter key. Even though the infor- 
mation in the existing Japanese DBCS master 
sort table is overridden, that table must exist 
before you can use this command. 


3. To update the Japanese DBCS active table to 
reflect the new copied information, use the 
SRTXBLD procedure in the System/36 or 
AS/Entry system environment, or the 
STRCGU command specifying OPTION(5). 
This must be done before you can use the 
sort utility to sort Japanese double-byte char- 
acters. 


Deleting a DBCS Sort Table 


Use the DLTIGCSRT command to delete a DBCS 
sort table from the system. 


When to Delete a DBCS Sort Table: 


Delete an unused DBCS sort table to free disk 
space, but you should always first save a copy of 
the table using the SAVOBJ command. You 
should delete the DBCS master sort table for a 
DBCS language if any of the following are true: 


1. You will not be creating any new characters 
for that language using the character gener- 
ator utility. 


2. You will not be using the sort utility to sort 
characters for that language. 


You should delete the DBCS active sort table for a 
DBCS language if you will not be using the sort 
utility to sort characters for that language. The 
DBCS active sort table must be on the system to 
use the sort utility for this language. 


How to Delete a DBCS Sort Table To 
delete a table, do the following: 


1. If desired, save the table onto tape or 
diskettes. See “Saving a DBCS Sort Table 
onto Tape or Diskette” on page D-12 for 
instructions. If you do not save the table onto 
removable media before deleting it, you will 
not have a copy of the table for future use. 


2. Enter the DLTIGCSRT command. 
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For example, to delete the DBCS sort table 
QCGACTYV, enter: 


DLTIGCSRT IGCSRT(QCGACTV) 


3. Press the Enter key. The system sends you a 
message when it has deleted the table. 


DBCS Conversion Dictionaries 


The DBCS conversion dictionary is a collection of 
alphanumeric entries and their related DBCS 
words. The system refers to the dictionary when 
performing DBCS conversion. See “How DBCS 
Conversion Works” on page D-20 for information 
on how the system uses the DBCS conversion 
dictionary during DBCS conversion. 


All DBCS conversion dictionaries have an object 
type of *IGCDCT. A system-supplied and a user- 
created dictionary are used with DBCS conver- 
sion. 


System-Supplied Dictionary (for 
Japanese Use Only) 


QSYSIGCDCT, the system-supplied dictionary that 
is stored in the library, QSYS, is a collection of 
entries with a Japanese pronunciation expressed 
in alphanumeric characters and the DBCS words 
related to those entries. The system checks this 
dictionary second when performing DBCS conver- 
sion. 


QSYSIGCDCT contains these entries: 
e Personal names 


— Family names 
— First names 


¢ Organization names 


— Private enterprises registered in the secu- 
rity market 

— Public corporations 

— Typical organizations in the central and 
local governments 

— Most universities and colleges 


e Addresses 


— Public administration units within the 
prefectures 
— Towns and streets in 11 major cities 


e Business terms, such as department names 
and position titles commonly used in enter- 
prises 


e Individual double-byte characters, including 
basic characters, as defined by IBM 


You cannot add or delete entries from this dic- 
tionary. However, you may rearrange the related 
DBCS words so that the words used most fre- 
quently are displayed first during DBCS conver- 
sion. See “Editing a DBCS Conversion Dictionary” 
on page D-16 for instructions on rearranging 
terms. 


User-Created Dictionary 


A user-created dictionary contains any alphanu- 
meric entries and related DBCS words that you 

choose to include. You might create a user dic- 
tionary to contain words unique to your business 
or words that you use regularly but that are not 

included in the system-supplied dictionary. 


You can create one or more DBCS conversion 
dictionaries with any name and store them in any 
library. When performing DBCS conversion, 
however, the system only refers to the first user 
dictionary named QUSRIGCDCT in the user’s 
library list, no matter how many dictionaries you 
have or what they are named. Make sure that the 
library list is properly specified so that the system 
checks the correct dictionary. 


During DBCS conversion, the system checks 
QUSRIGCDCT before checking QSYSIGCDCT. 


Commands for DBCS Conversion 
Dictionaries 


You can use the following commands to perform 
object management functions with the DBCS con- 
version dictionary. Specify the 
OBJTYPE(*IGCDCT) parameter when entering 
these commands: 


¢ CHGOBJOWN: Change the owner of a 
DBCS conversion dictionary 

¢ CHKOBJ: Check a DBCS conversion dic- 
tionary 

¢ CRIDUPOBUJ: Create a duplicate object of 
the dictionary 

¢ DMPOBJ: Dump a DBCS conversion dic- 
tionary 


¢ DMPSYSOBJ: Dump the system-supplied 
dictionary 

¢ DSPOBJAUT: Display a user’s authority to 
the dictionary 

¢ GRTOBJAUT: Grant authority to use the dic- 
tionary 

¢ MOVOBuJ: Move the dictionary to another 
library 

e RNMOBJ: Rename the dictionary 

e RSTOBJ: Restore the dictionary 

e RVKOBJAUT: Revoke authority to use the 
dictionary 

e SAVCHGOBuU: Save a changed dictionary 

e SAVOBJ: Save the dictionary 


The system saves or restores DBCS conversion 
dictionaries when you use these commands: 


¢ RSTLIB: Restore a library in which the dic- 
tionary is stored 

¢ SAVLIB: Save a library in which the dic- 
tionary is stored 

e SAVSYS: Save QSYSIGCDCT, the system 
DBCS conversion dictionary, when saving the 
system 


Creating a DBCS Conversion Dic- 


tionary: To create a DBCS conversion dic- 
tionary, do the following: 


1. Use the Create DBCS Conversion Dictionary 
(CRTIGCDCT) command. 


2. Name the dictionary, QUSRIGCDCT, so it can 
be used during DBCS conversion. The 
system uses the dictionary if it is the first user- 
created dictionary found when searching a 
user’s library list. 


You might call the dictionary by another name 
while it is being created to prevent application 
programs from using it for conversion. Later, 
change the dictionary name using the 
Rename Object (RNMOBJ) command. 


For example, to create a user DBCS conver- 
sion dictionary to be stored in the library 
DBCSLIB, enter: 


CRTIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT) 


3. Use the EDTIGCDCT command to put entries 
and related words into the dictionary after cre- 
ating it. See “Editing a DBCS Conversion 
Dictionary” on page D-16 for instructions on 
putting entries in the dictionary. 
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Editing a DBCS Conversion 


Dictionary: Use the Edit DBCS Conversion 
Dictionary (EDTIGCDCT) command to edit the 
DBCS conversion dictionary. Use editing to add 
user-defined characters to the dictionary, so that 
users can enter characters using DBCS conver- 
sion, and rearrange terms in a DBCS conversion 
dictionary to suit individual needs. 


Requirements for a DBCS Conversion Dic- 
tionary: The display station needed for use while 
editing the DBCS conversion dictionary depends 
on the value that you entered for the ENTRY 
parameter on the EDTIGCDCT command: 


e lf you specified a specific string with the 
ENTRY parameter or if you want to display 
double-byte characters, you must use a DBCS 
display station. 


e lf you did not specify a specific string with the 
ENTRY parameter, or if you do not want to 
display double-byte characters, use either a 
DBCS display station, or a 24-row by 
80-column alphanumeric display station. 


DBCS Conversion Dictionary Operations: You 
may perform the following editing operations on a 
user-created DBCS conversion dictionary: 


e Add entries to the dictionary (including adding 
the first entries to the dictionary after it is 


created). The dictionary can contain as many 
as 99,999 entries. 

¢ Delete entries from the dictionary. 

¢ Change entries in the dictionary, such as 
replacing the DBCS words related to an 
alphanumeric entry. 

e Move the DBCS words related to an alphanu- 
meric entry to rearrange the order in which 
they appear during DBCS conversion. 


The only editing function that you can perform with 
QSYSIGCDCT, the system-supplied dictionary, is 
to move DBCS words related to an alphanumeric 
entry. Move words in order to rearrange the order 
in which they appear during DBCS conversion. 


Displays Used for Editing a DBCS Conversion 
Dictionary: After you enter the EDTIGCDCT 
command, the system presents either the Work 
With DBCS Conversion Dictionary display or the 
Edit Related Words display, depending on the 
value entered for the ENTRY parameter on the 
command. 


Work with DBCS Conversion Dictionary Display: 
Use this display to work with alphanumeric entries, 
such as choosing an entry to edit or deleting an 
entry. The system displays the Work with DBCS 
Conversion Dictionary display if you enter *ALL or 
a generic string for the ENTRY parameter of the 
EDTIGCDCT command. 
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See the discussion of the EDTIGCDCT command 
in the CL Reference for a complete description of 
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the Work with DBCS Conversion Dictionary 
display. 


Edit Related Words Display: Use this display to 

work with the DBCS words related to an alphanu- 
meric entry. The system displays the Edit Related 
Words display if you enter a specific string for the 
ENTRY parameter. The system also displays the 


Edit Related Words display if you choose an entry 
to edit from the Work with DBCS Conversion Dic- 
tionary display. Following is an example of the 
Edit Related Words display: 
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See the discussion of the EDTIGCDCT command 
in the CL Reference for a complete description of 
the Edit Related Words display. 


Examples of Editing Operations: The following 
sections give examples of the editing operations 
that you can perform using the EDTIGCDCT dis- 
plays: 

¢ Beginning to edit a dictionary 

e Adding the first entries in a dictionary 

¢ Deleting an entry 

e Moving a related word 

e Ending editing the dictionary 


Beginning to Edit a Dictionary: Enter the 
EDTIGCDCT command to start editing the dic- 
tionary for any type of editing operation. For 
example, to put the first entry in the dictionary, 
enter: 


EDTIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT) ENTRY(*ALL) 


Or, to edit the entries beginning with the string 
ABC enter: 


EDTIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT) ENTRY('ABC') 
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Adding the First Entries in a Dictionary: To 
add the first entries into a dictionary, do the fol- 
lowing: 


1. Specify ENTRY(*ALL) when entering the 
EDTIGCDCT command. For example, to edit 
the dictionary QUSRIGCDCT stored in the 
library DBCSLIB, enter: 


EDTIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT) ENTRY (*ALL) 


The system displays the Work with DBCS 
Conversion Dictionary display. 


2. Enter a 1 in the first option field in the list and 
enter an alphanumeric entry to be added to 
the dictionary in the entry field. 


The system then displays the Edit Related 
Words display showing only two lines of data: 
BEGINNING OF DATA and END OF DATA. 


3. Enter an | in the NBR field beside the 
BEGINNING OF DATA line to insert a line. 


4. Press the Enter key. The system displays a 
blank line. 


5. On the blank line, enter a DBCS word to be 
related to the new alphanumeric entry. 


If you enter data on the inserted line and 
leave the cursor on that line, another new line 
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appears below when you press the Enter key. 
You can enter another DBCS word on this 
line, or delete it by leaving it blank, and 
pressing the Enter key. 


6. When you finish adding this first entry, press 
F12 to get the Exit Dictionary Entry display. 
Enter the Y option to save the entry and then 
return to the Work With DBCS Conversion 


Dictionary display. Enter option 1 again and 
enter another alphanumeric entry in the entry 
field to continue adding entries to the dic- 
tionary, or press F3 to end editing the dic- 
tionary. 


Deleting an Entry: Enter a 4 in the input field 
beside the entry to be deleted as follows: 
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Moving a Related Word: Moving the words 
related to an alphanumeric entry changes the 
order in which the words appear during DBCS 
conversion. To move a word, do the following: 


1. Display the Edit Related Words display for the 


entry in which you want to move DBCS words, 


either by entering a specific entry with the 
EDTIGCDCT command, or by choosing an 
entry to edit from the Work with DBCS Con- 
version Dictionary display. 


2. When the display appears, enter an M in the 
NBR field beside the DBCS word to be 
moved. 


3. Enter an A in the NBR field of the line after 
which the word will be moved. 


4. Press the Enter key. The system moves the 


word, on the line marked M to a position imme- 


diately following the line marked with an A. 
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Ending the Editing Process: To end the editing 
operation, press F3. The Exit Dictionary Entry 
display is displayed, and you can choose to save 
the entry or not. The system then returns you to 
your basic working display, such as the Command 
Entry display. 


Suggestions for Editing the Dictionary: When 
editing the DBCS conversion dictionary, consider 
the following: 


e You can use DBCS conversion with the Edit 
Related Words display to enter related words 
into a user-created dictionary. See “DBCS 
Conversion (for Japanese Use Only)” on 
page D-19 for information on this procedure. 


e Place the most commonly used DBCS words 
at the beginning of the list of related words on 
the Edit Related Words display. This simpli- 
fies DBCS conversion because the system 
displays the related words in the same order 
in which those words are listed in the dic- 
tionary. 


Displaying and Printing the DBCS 
Conversion Dictionary 


Use the Display DBCS Conversion Dictionary 
(DSPIGCDCT) command to display and print the 
DBCS conversion dictionary. You can display or 
print the entire dictionary or just a certain part of it, 
depending on the value you specify for the 
ENTRY parameter. 


For example, to print the entry ABC from the dic- 
tionary QUSRIGCDCT and its related words, 
enter: 


DSPIGCDCT IGCDCT(DBCSLIB/QUSRIGCDCT) + 
ENTRY(ABC) OUTPUT (*PRINT) 


To display all of the entries from the system- 
supplied dictionary QSYSIGCDCT and their 
related words, enter: 


DSPIGCDCT IGCDCT(QSYS/QSYSIGCDCT) 


Following is an example of the display produced 
by the DSPIGCDCT command. It shows alphanu- 
meric entries and their related words. 


(~ RERIRESORR ) 
Me... QSYSIGCDCT af: | = 
SATFSN- 1: QSYS 
#S JAA es Maas 
1? lox 
2 + 
3 2 
4 \ 
5 ov 
6 “” 
1 
8 2 
9 # 
10 % 
li oF 
12 & 
13° No 
= . BEC... 
GATT SHI, RITF—- SALT RAV 
F3= YT FL2= BRL 
ie Z 


See the discussion of the DSPIGCDCT command 
in the CL Reference for a complete description of 
the command and the display it produces. 


Deleting a DBCS Conversion 
Dictionary 


Use the Delete DBCS Conversion Dictionary 
(DLTIGCDCT) command to delete a DBCS con- 
version dictionary from the system. 


In order to delete the dictionary, you must have 
object existence authority to the dictionary and 
object operational authorities to the library in 
which the dictionary is stored. 


When you delete a dictionary, make sure that you 
specify the correct library name. It is possible that 
many users have their own dictionaries, each 
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named QUSRIGCDCT, stored in their libraries. If 
you do not specify any library name, the system 
deletes the first DBCS conversion dictionary in 
your library list. 


For example, to delete the DBCS conversion dic- 
tionary QUSRIGCDCT in the library DBCSLIB, 
enter: 


DLTIGCDCT IGCDCT (DBCSLIB/QUSRIGCDCT) 


DBCS Conversion (for Japanese 
Use Only) 


When you use DBCS display stations to enter 
double-byte data, you may use the various data 
entry methods supported on the display station, or 
you may choose to use the AS/400 DBCS conver- 
sion support. DBCS conversion lets you enter an 


D-19 


alphanumeric entry or DBCS code and convert the 
entry or code to its related DBCS word. DBCS 
conversion is intended for Japanese character 
sets and its use is limited for application to other 
double-byte character sets. 


Specifically, DBCS conversion lets you convert the 
following: 


¢ Astring of alphanumeric characters to a 
DBCS word 

¢ English alphanumeric characters to double- 
byte alphanumeric characters 

¢ Alphanumeric Katakana to double-byte 
Hiragana and Katakana letters 

e A DBCS code to its corresponding double- 
byte character 

e¢ A DBCS number to its corresponding double- 
byte character 


Where You Can Use DBCS 
Conversion 


You can use DBCS conversion in the following 
instances: 


e When entering data into input fields of certain 
SEU displays. For information about which 
fields you can use with DBCS conversion, 
refer to the ADTS/400: Source Entry Utility. 


e When prompting for double-byte data using 
QCMDEXEC. For instructions on this proce- 
dure, see the CL Reference. 


e When entering data into input fields of DBCS 
display files in user-written applications. 
Specify DBCS conversion with the DDS 
keyword IGCCNV. See the DDS Reference 
for information on this keyword. 


e¢ When editing the related words on the Edit 
Related Words display, which is displayed 
when editing the DBCS conversion dictionary 
(EDTIGCDCT command). See “Editing a 
DBCS Conversion Dictionary” on page D-16 
for information on the Edit Related Words 
display. 


How DBCS Conversion Works 


DBCS conversion is an interactive function 
between you and the system in which you enter 
an alphanumeric entry. The system displays 
related DBCS words, and you choose which word 
to use. 
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The system determines which words are related to 
an alphanumeric entry by checking DBCS conver- 
sion dictionaries. The system checks two DBCS 
conversion dictionaries when performing DBCS 
conversion. It checks the first user-created dic- 
tionary named QUSRIGCDCT found when 
searching a user’s library list. Then, it checks the 
system-supplied dictionary, QSYSIGCDCT, stored 
in the library QSYS. (QSYSIGCDCT contains only 
Japanese double-byte characters.) You can 
create other user dictionaries, and you can give 
them names other than QUSRIGCDCT, but the 
system only refers to the first user-created dic- 
tionary named QUSRIGCDCT found in your library 
list when performing DBCS conversion. 


After checking the dictionaries, the system dis- 
plays words related to the alphanumeric entry. 
You then position the cursor under the word of 
your choice, and press the Enter key. The system 
enters that word where the cursor was positioned 
when you began DBCS conversion. 


Using DBCS Conversion 


You can change the user-defined dictionary used 
during DBCS conversion. Before you change the 
user-defined dictionary, end your application 
program or end the command that the system is 
performing. Then change the dictionary that is 
used by changing the library list (using the 
CHGLIBL command). 


You can create your own DBCS conversion dic- 
tionary for DBCS conversion. The system- 
supplied dictionary is a collection of entries with a 
Japanese pronunciation expressed in alphanu- 
meric characters and Japanese DBCS words 
related to the entry. See “Creating a DBCS Con- 
version Dictionary” on page D-15 for instructions 
on this procedure. 


If no user-created dictionary is found, the system 
refers only to QSYSIGCDCT. See “DBCS Con- 
version Dictionaries” on page D-14 for more infor- 
mation on creating and using DBCS conversion 
dictionaries. 


Performing DBCS Conversion 


The following procedure describes how to convert 
one alphanumeric entry to its related DBCS word 
using DBCS conversion. You must start DBCS 
conversion separately for each field in which you 
want to enter double-byte data. 


Note: DBCS conversion is intended for Japanese 
data entry. Its use with other languages is limited. 


While performing DBCS conversion, you can 
display information about the function by pressing 
the Help key. Help is available until you end 
DBCS conversion. 


1. Position the cursor in the field in which you 
want to enter double-byte characters. Insert 
shift-control characters into the field if they 
have not yet been inserted. To find out how 
to insert shift characters, see “Inserting Shift- 
Control Characters” on page D-6. 


2. Position the cursor under the shift-in char- 
acter, in a blank area between the shift-control 
characters, or under a double-byte character. 


3. Press the function key used to start DBCS 
conversion. 


In SEU, as well as from the Edit Related 
Words display (displayed when using the 
EDTIGCDCT command), press F 18. 


4. Enter the following values: 
a. In the first field, enter one of the following: 


I Inserts the converted word before 
the character under which you posi- 
tioned the cursor in step 2. 


R__ Replaces the character under which 
you positioned the cursor in step 2 
with the converted word. 


b. In the second field, enter one of the fol- 
lowing: 


1) A string of alphanumeric characters to 
be converted. The string can have as 
many as 12 characters. 


2) The 4-character DBCS code of a 
double-byte character. 


3) The 2- to 5-digit DBCS number of a 
double-byte character. 


c. In the third field, enter one of the following 
conversion codes: 


No entry Converts the entry in field B 
from alphanumeric to double- 
byte by referring to the DBCS 
conversion dictionaries. 


G Converts the 2- to 5-digit 
DBCS number in field B to the 
character it represents. 


H Converts the entry in field B to 
double-byte Hiragana, upper- 
case alphabetic, numeric, or 
special characters. 


K Converts the entry in field B to 
double-byte Hiragana, lower- 
case alphabetic, numeric, or 
special characters. 


X Converts the 4-character 
DBCS code to the character it 
represents. 


5. Press the Enter key. The system displays 
words related to the entry in the second field. 


If you see a plus (+) sign following the last 
displayed word, the system has additional 
words to display. Press the Roll Up key to 
see these entries. Then, to return to a word 
displayed earlier, press the Roll Down key. 


If a word is shown in a reverse image, the 
word contains an imbedded blank. 


6. Choose the DBCS word from the last field that 
best suits your needs by positioning the cursor 
under that DBCS word. 


7. Press the Enter key. The system enters the 
word where the cursor was positioned in step 
2, either by inserting the word or by replacing 
another word, depending on what you entered 
in the first field. 


8. Do one of the following: 


a. Continue using DBCS conversion. Repeat 
steps 4 through 7 until you finish entering 
data into the field. 


b. End DBCS conversion by pressing the 
same function key used to start conver- 
sion. The system automatically ends the 
conversion when you reach the end of the 
field. 


In SEU, as well as from the Edit Related 
Words display (displayed when using the 
EDTIGCDCT command), press F18. 
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Converting One Alphanumeric Entry to a 
Double-Byte Entry: The following example 


Note: Until DBCS conversion is ended, 
you cannot perform any other system 


function. For example, the F3 key cannot shows how to convert one entry and enter it into a 
be used to exit an SEU display. field. 
1. Position the cursor in the field in which you 
Examples want to enter double-byte data. 
Position the cursor here. 
(— a 
voy 9h %  : EMPMAINT 
Et : 91/05/23 A #/f8 Rok FT ame : EMPMAINTE 
+ASs : 12002 G PEs FE 
y] 
SUEPA 
AUER _ ss HRT ATH 
gS ail 
AMMA _ ss THT 


Mifl2—F _ WRAL ER 
BRERA — FR Ep 
65 _ sak 


FS: &YT F18: 0 +R AR 


“ 
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2. Insert shift-control characters into the field. 3. Press the function key used to start DBCS 


See “Inserting Shift-Control Characters” on 
page D-6 for instructions on inserting shift- 
control characters. 
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conversion. For the display just shown, the 
function key is F18. The system displays a 
prompt line. 


Notice that shift control characters 
have been inserted into the field. 


( 7 oy jh % + EMPMAINT 
Aft : 91/05/23 A\® t8 oR F mime : EMPMAINTE 
tHABS : 12002 ia ee 3 :|) eS | 
J 
BLE 
AUGHAY TAT, 
A 
AMaAAe THAT Z, 


RifZ2— KF _ Weep 
ARI KF _ ARERR 
m5 aI 


FS: &Y P18: A+ BAER 


1 
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The prompt line. 


Because the cursor was placed under a 4. Enter an alphanumeric entry to be converted 
shift-in character when conversion was in the second field. 
started, conversion automatically is set to | Leave the third field blank. 
(inserting the converted word). 
(~ TOI: EMPMAINT. ) 

Aff : 91/05/23 AS ff RR F wine : EMPMAINTE 

ttAGs : 12002 a —_—~—é‘iESYY = 

7 

SUE 

AERA THBTETS 

AR 

AGAR _ = RTA 


Wfira-K _ BRALGéer 
Rea — FMR eA) 


65 aR 
F3.: &T P18: D+F 
Lim 
\S \ it 
Enter an alphameric entry here. al 
5. Press the Enter key. The system displays 6. Position the cursor under the DBCS word that 
related DBCS words. you want to enter, if that word is not the first 
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DBCS word shown. In the following example, 
the first word is the one to be entered. 


a 
Aft : 91/05/23 ABW Ha T 


HABS : 12002 KA 


TH t 
BUEA 
MAAS ss TBH 
HH 
aa TTA 


Rifra—F _ Rep 
ARR I KF _ BRS Pp 
65 _ i 


F323: #&T 


lid. _.._ #H mH FE we me HA 


Toye: EMPHAINT 
aims : EMPMAINTE 


fea El 


F18: EAE 


‘ _ # 
Position the cursor here. eeere 
7. Press the Enter key. The DBCS word is 
entered into the field. 
The system enters the word into the field. 
(~ 709° 5k % =: EMPMAINT 
Ett: 91/05/23 A S/R RoR wine : EMPMAINTE 
HABS : Ae Hie ER 
NF 
BUERT 
AGHAZ ss TART AT 
ARH 
AGS ss TAT 
Rira— Fk _ WR E, 
RI KF _ RAE 
e@5 _ HR 
F3: &T PI8: AF BPR 
Claaeeaeee J 
HRSLS325-0 
Converting Many Alphanumeric Entries at One 1. Enter as many alphanumeric entries as will fit 
Time: You do not have to continually start DBCS into field B. Separate each entry by a blank. 


conversion for each alphanumeric entry. Instead, 


you can do the following: 
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Field B contains space for 12 alphanumeric 
characters: 


These are the entries to be converted. 


I XXX_YYY_ZZZ_ _ 
A B C D 


The system converts the entries one at a time, 
in the order entered. When the system con- 
verts an entry, the system displays the DBCS 
words related to that entry in field D. 


2. Position the cursor under the DBCS word that 
you want to use. 


3. Press the Enter key. Then, the system 
adjusts field B; the next entry is moved to the 
position farthest left of the field. The DBCS 
words related to that entry are displayed in 
field D. 


At this time, you can enter additional alphanu- 
meric entries to be converted at the end of 
field B. 


Converting Alphanumeric Blanks to DBCS 
Blanks: You can convert alphanumeric blanks 
(one position wide) to DBCS blanks (two positions 
wide, the same width as double-byte characters) 
using DBCS conversion. 


To convert blanks, do the following: 


1. Enter one or more blanks in field B. 


A B C D 

2. Press the Enter key. The system displays in 
field D the same number of DBCS blanks as 
the alphanumeric blanks that you entered in 
field B. The DBCS blanks are displayed in 
reverse image. 


3. Press the Enter key again. The system enters 
the DBCS blanks into the field where you 
started DBCS conversion. 


Changing Alphanumeric Entries or Conversion 
Code: lf none of the related words shown during 
conversion are suitable candidates for the alpha- 
numeric entry, and you would like to try a conver- 
sion again (by using a different type of conversion 
or a different alphanumeric entry), do the fol- 
lowing: 


1. Move the cursor to field B. For example: 


Move the cursor here. 


XXXXXX 
A B c D 
2. Do one of the following: 

a. Position the cursor under the first position 
of the field in which you want to enter 
alphanumeric entries. 

b. Enter a different alphanumeric entry. 


c. Change the conversion code in field C, 
such as from H to K. 


3. Press the Enter key. 


4. Continue DBCS conversion. 


Using DBCS Conversion to Enter Words in the 
DBCS Conversion Dictionary: You can use 
DBCS conversion when entering DBCS words on 
the Edit Related Words display. 


To start DBCS conversion, do the following: 


1. Position the cursor at the position where the 
DBCS word is to be entered. 


2. Press F18. The system displays the conver- 
sion prompt line at the bottom of the display. 


Perform DBCS conversion according to the 
instructions described in “Performing DBCS 
Conversion” on page D-21. 


Note: You must start and end DBCS conversion 
separately for each line of data. 


Considerations for Using DBCS Con- 


version: Consider the following when per- 
forming DBCS conversion: 


¢ You can only perform DBCS conversion at a 
DBCS display station, using the 5556 key- 
board. 


¢ You may use DBCS conversion to insert or 
replace characters only if the line in which 
double-byte characters are to be inserted has 
sufficient space. 


— The space available for inserting charac- 
ters is equal to the number of characters 
from the last character on the line that is 
not blank to the right edge of the display. 

— The space available for replacing charac- 
ters is equal to the number of characters 
from the cursor position (including the 
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character marked by the cursor) to the — lf you ignore the message and press the 
end of the DBCS portion of the field. Enter key again, the system truncates the 
characters in excess of the limit from the 
right side of the string to be inserted or 
replaced. 


The following happens when you do not have 
enough space: 


— If you try to insert or replace a string of 
characters where there is no space avail- 
able, the system sends a message. 
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Appendix E. Display File Return Codes 


This section contains descriptions of all major and 
minor return codes for display files. These return 
codes are set in the I/O feedback area of the 
display file. The return codes report the results of 
each operation. The appropriate return code is 
available to the application program that issued 
the operation. The program then checks the 
return code and acts accordingly. Refer to your 
high-level language manual for information about 
how to access these return codes. 


The return code is a four-digit value: the first two 
digits contain the major code, and the last two 
digits contain the minor code. With some return 
codes, a message is also sent to the job log or 
the operator message queue (QSYSOPR). You 
can refer to the message for additional informa- 
tion. 


condition that may be significant to your 
program even though it is not an error. 


Messages: 


CPF4018 (Status) 

CPF4019 (Diagnostic 
CPF4054 (Diagnostic 
CPF4082 (Diagnostic 
CPF4410 (Diagnostic 
CPF5003 (Status) 

CPF5508 (Diagnostic) 


Ys Ss ws 


Major Code 00 


Major Code 00—Operation completed suc- 
cessfully. 


Description: The operation issued by your 
program completed successfully. 


Action: Continue with the next operation. 


Major Code 02 


Major Code 02-Input operation completed 
successfully, but your job is being ended (con- 
trolled). 


Description: The input operation issued by 
your program was completed successfully. 
However, your job is being ended (controlled). 


Action: Your program should complete its 
display processing as soon as possible to 
allow your program to complete in an orderly 
manner. The system eventually changes a job 
ended (controlled) to a job ended (immediate) 
and forces all processing to stop for your job. 


Code  Description/Action 


0000 _ ~=—Description: For input operations per- 
formed by your program, 0000 indicates 
that some data was received on a suc- 
cessful input operation. 


For output operations performed by your 
program, 0000 indicates that the last 
output operation completed successfully. 


Action: Your program may continue. 
One of the messages listed below may 
have been issued to warn of an unusual 
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Code Description/Action 


0200 Description: On a successful input oper- 
ation, an indication was received that a 
job ended (controlled) request is pending. 
Also, 0200 indicates that some data was 
received. 


Action: Your program may continue. 
However, the recommended action is to 
complete the display processing and end 
the program, because the system will 
eventually cancel your job and cause all 
processing to stop for your job. 


E-1 


Major Code 03 


Major Code 03-—Input operation completed 
successfully, but no data received. 


Description: The input operation was com- 
pleted successfully, but no data was received. 


Action: Check the minor return code for addi- 
tional information, and continue with the next 
operation. 


Code Description/Action 


0300 


0309 


0310 


Description: No data was received on a 
successful input operation. Examples of 
conditions causing this are no data being 
available on a get-relative or a get-next- 
changed operation to a subfile record 
format. 


Action: Continue with whatever pro- 
cessing is appropriate. For example, if 
your program issued a get-next-changed 
operation to a subfile record format, then 
a 0300 indicates that there are no more 
subfile records changed by the user and 
no more user input data to process. 


Messages: 


CPF5017 (Notify) 
CPF5020 (Notify) 
CPF5037 (Notify) 


Description: Your program is being 


ended (controlled). No data was received. 


This return code is only applicable to the 
read-from-invited-devices operation. 


Action: Your program can continue pro- 
cessing. However, the recommended 
action is to complete the display pro- 
cessing and end the program, because 
the system will eventually cancel your job 
and cause all processing to stop for your 
job. 


Messages: 
CPF4741 (Notify) 


Description: The time interval specified 
by the WAITRCD value for the display file 
has ended. 
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This return code is only applicable to the 
read-from-invited-devices operation. 


Note: Because no device is associated 
with the completion of this operation, the 
device name in the I/O feedback area 
contains an *N. 


Action: Issue the operation to perform 
the intended function after the specified 
time interval has ended. For example, if 
you are using the time interval to control 
the length of time to wait for data, you can 
then issue another read-from-invited- 
devices operation to receive the data. 


Messages: 


CPF4742 (Status) 
CPF4743 (Status) 


Major Code 04 


Major Code 04—Output exception occurred. 


Description: An output exception occurred 
because your program attempted to send 
output when it should have been receiving the 
data that had already been sent by the 
display. Your data, associated with this output 
operation, was not sent to the display. Your 
program can attempt to send its output later. 


Action: Issue an input operation to receive 
the data. 


Code _ Description/Action 


0412 


Description: An output exception 
occurred because your program attempted 
to send data when it should have been 
receiving the data that had already been 
sent by the display. Your program data 
was not sent and should be sent later, 
after the data from the display has been 
received. 


Action: Issue an input operation to 
receive the data. 


Messages: 
CPF4737 (Notify) 


Major Codes 08-11 


Major Codes 08 and 11—Miscellaneous 
program errors occurred. 


Description: The operation just attempted by 
your program was not successful. The opera- 
tion may have failed because it was issued at 
the wrong time. 


Action: Refer to the individual return code 
descriptions for the appropriate recovery 
actions. 


Code _ Description/Action 


0800 Description: The acquire operation just 
performed was not successful. It tried to 
acquire a device that had already been 
acquired. 


Action: If the display device requested 
by the original acquire operation is the 
one needed, your program can begin 
using it because it is already available. If 
a different device is required, issue 
another acquire operation for a different 
device name. 


Messages: 


CPD4077 (Diagnostic) 
CPF50A0 (Status) 


1100 Description: The read-from-invited- 
devices operation was not successful 
because no devices were invited. 


Action: Issue an invite function followed 
by a read-from-invited-devices operation. 


Messages: 
CPF4740 (Notify) 


Code _ Description/Action 


3431 Description: The input operation issued 


by your program was not successful 
because the length of the data received 
from the display exceeds the receive data 
length specified in the user-defined data 
stream. The data received is truncated. 


This return code is only applicable to input 
operations using a record format speci- 
fying a user-defined data stream 
(USRDFN DDS keyword). 


Action: Close the device file and end 
your program. Then, change your 
program so that the input record length is 
at least as long as the data record to be 
received. 


Messages: 
CPF5062 (Notify) 


Major Code 80 


Major Code 34 


Major Code 80-—Permanent system or file 
error (not recoverable). 


Description: A file or system error that is not 
recoverable has occurred. Recovery is 
unlikely until the problem causing the error has 
been corrected. 


Action: The following general actions can be 
taken by your program for each 80xx return 
code. Other specific actions are given in each 
return code description. 


¢ Continue processing without the display. 

¢ Close the device file and open the file 
again. If the operation is still unsuc- 
cessful, try it again only a limited number 
of times. (The number of times should be 
specified in your program.) 

e End. 


Major Code 34—Input exception occurred. 


Description: The input operation attempted 
by your program was not successful. The 
data received was too long for the record 
format specified on the input operation. 


Action: Refer to the individual return code 
descriptions for the appropriate recovery 
actions. 


Code Description/Action 


8081 Description: The operation was not suc- 


cessful because a system error condition 
was detected. 


Action: Your display device may need to 
be varied off and then on again. Your 
program can either: 
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8082 


80A6 


¢ Continue processing without the 
display device. 

¢ Close the device file and open the file 
again. 

e End. 


Messages: 


CPF4182 (Escape 
CPF4510 (Escape 
CPF5192 (Escape 
CPF5257 (Escape 
CPF5403 (Escape 
CPF5404 (Escape 


)  CPF5416 (Escape 
) 
) 
) 
) 
) 
CPF5405 (Escape) 
) 
) 
) 
) 
) 
) 


CPF5418 (Escape 
CPF5423 (Escape 
CPF5429 (Escape 
CPF5431 (Escape 
CPF5433 (Escape 
CPF5434 (Escape 
CPF5441 (Escape 
CPF5447 (Escape 
CPF5455 (Escape 
CPF5456 (Escape 
CPF5507 (Escape 


CPF5408 (Escape 
CPF5409 (Escape 
CPF5410 (Escape 
CPF5411 (Escape 
CPF5414 (Escape 
CPF5415 (Escape 


) 
) 
) 
) 
) 
) 
) 
) 
) 
) 
) 
) 


Description: The operation was not suc- 
cessful because the display device is 
unusable. This may occur because a 
cancel reply has been taken to an error 
recovery message for the device or 
because the display has been held by a 
Hold Communications Device 
(HLDCMNDEV) command. No operations 
should be issued to the device. 


Action: Communications with the display 
cannot be resumed until the device has 
been reset to a varied-on state. If the 
device has been held, use the Release 
Communications Device (RLSCMNDEV) 
command to reset the device. If the 
device is in an error state, vary the device 
off and then on again. Once the device is 
reset, normal operation can be started by 
opening the display device file again. 
Your program can either: 


¢ Continue processing without the 
display device. 

¢ Close the device file and open the file 
again. 

e End. 


Messages: 


CPF4354 (Escape) 
CPF5269 (Escape) 


Description: A Systems Network Archi- 
tecture (SNA) unbind operation was not 
successful on a close or release opera- 
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80B3 


80C0 


tion. This may be the result of a device 
configuration error. The device may be 
unusable. No operations should be 
issued to the device. 


Action: Refer to the device response 
code in the accompanying error message 
to determine the cause of the failure. 
Vary the device off and then on again to 
reset the error. Correct the error and try 
your program again. 


Messages: 
CPF4527 (Escape) 


Description: The open operation was not 
successful because the display file is not 
available. The file cannot be opened 
again until the necessary resources are 
available. 


Action: Your program can wait for the 
display file to become available, then 
issue another open operation. Otherwise, 
you may continue other processing or end 
the program. 


Consider increasing the WAITFILE param- 
eter with the Change Display File 
(CHGDSPF) command or Override with 
Display File (OVRDSPF) command to 
allow more time for the file to become 
available. 


Messages: 
CPF4128 (Escape) 


Description: An error that is not recover- 
able has occurred on the display device. 


Action: Your display devices may need 
to be varied off and then on again. Your 
program can either: 


¢ Continue processing without the 
display station. 

¢ Close the device file and open the file 
again. 

e End. 


Messages: 


CPF5103 (Escape) 
CPF5192 (Escape) 
CPF5412 (Escape) 
CPF5413 (Escape) 
CPF5419 (Escape) 


CPF5420 (Escape) 
CPF5421 (Escape) 
CPF5430 (Escape) 
CPF5437 (Escape) 
CPF5439 (Escape) 


80EB 


80ED 


80F8 


Description: An open operation was not 
successful because an open option that is 
not valid or a combination of options that 
is not valid was specified in your program, 
in the display file, or in an override 
command. 


Action: Close the display file, correct the 
problem, and open the file again. See the 
individual messages to determine what 
options are not valid. 


Messages: 


CPF4062 (Escape 
CPF4129 (Escape 
CPF4148 (Escape 
CPF4156 (Escape 
CPF4163 (Escape 
CPF4169 (Escape 
CPF4191 (Escape 
CPF4238 (Escape 


)  CPF4345 (Escape) 
)  CPF5151 (Escape) 
)  CPF5510 (Escape) 
)  CPF5511 (Escape) 
)  CPF5512 (Escape) 
)  CPF5513 (Escape) 
)  CPF5552 (Escape) 
) 
Description: The open operation was not 
successful because the record format 
descriptions in the file have changed since 
your program was compiled. 


Action: Close the file and end the 
program. Determine whether the changes 
affect your application program. If they 
do, recompile the program. If the changes 
do not affect your program, the file should 
be changed or overridden to 
LVLCHK(*NO). When LVLCHK(*NO) is 
specified, the system does not compare 
the record format descriptions. 


Messages: 
CPF4131 (Escape) 


Description: An operation to a file was 
not successful because the file is marked 
in error. 


Action: Close the file. Refer to mes- 
sages in the job log to determine what 
errors occurred. Take the appropriate 
action for those errors. 


Messages: 


CPF4132 (Escape) 
CPF4213 (Escape) 
CPF4550 (Escape) 


CPF5129 (Escape) 
CPF5144 (Escape) 
CPF5427 (Escape) 


Major Code 81—Permanent device error (not 
recoverable). 


Description: A device-related error that is not 
recoverable occurred during an I/O operation. 
Any attempt to continue using this display 
device will probably fail again until the cause 
of the problem is found and corrected, but 
operations directed to other display devices 
associated with the file should be expected to 
work. 


Action: The following general actions can be 
taken for each 81xx return code. Other spe- 
cific actions are given in each return code 
description. 


¢ Continue processing without the display 
device. 

e Release the device or close the file, 
correct the problem, and acquire the 
device again or open the file. If the opera- 
tion is still unsuccessful, try it again only a 
limited number of times. (The number of 
times should be specified in your 
program.) 

e End. 


Several return codes indicate that an error 
condition must be corrected by varying the 
device off and on again. 


Major Code 81 


Code _ Description/Action 


8181 Description: A system error condition 


was detected during the I/O operation to 
the device. 


Action: Release the device in error or 
close the file. You may need to vary the 
device off and on again to clear the error. 
Determine the cause of the failure from 
the accompanying message. Check for 
any system operator messages indicating 
that additional corrective action must be 
performed. Open the file again or acquire 
the device to continue. 


Messages: 


CPF4553 (Escape) 
CPF4725 (Escape) 
CPF5105 (Escape) 
CPF5189 (Escape) 
CPF5254 (Escape) 
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8191 


8197 


81C2 


Description: The operation was not suc- 
cessful because a permanent line error 
occurred, and the system operator took a 
recovery option in response to the line 
error message. (You can find out what 
type of line error occurred by asking the 
system operator.) The device has been 
marked unusable. 


Action: Release the device in error or 
close the file. Vary the device off and on 
again to clear the error. Open the file 
again or acquire the device to continue. 


Messages: 


CPF4526 (Escape) 

CPF4542 (Escape) 

CPF4551 (Escape) 

CPF5128 (Escape) 

CPF5143 (Escape) 

CPF5198 (Escape) 

Description: An error condition that is 
not recoverable was detected at the 
device. An example of such an error is 
the user turning off the display device. 


Action: Release the device in error or 
close the file. The display device may 
need to be varied off and then on again to 
clear the error. Refer to the accompa- 
nying error message for additional infor- 
mation regarding the source of the specific 
error detected. Open the file or acquire 
the device again to continue. 


Messages: 


CPF4149 (Escape 
CPF4197 (Escape 
CPF4524 (Escape 
CPF4533 (Escape 
CPF4538 (Escape 
CPF5047 (Escape 


)  CPF5106 (Escape) 

) CPF5140 (Escape) 

)  CPF5143 (Escape) 

)  CPF5199 (Escape) 

)  CPF5265 (Escape) 

) 

Description: The operation issued by 
your program was not successful because 
the Systems Network Architecture (SNA) 
session with the display is not active. 


Action: Release the device or close the 
file. Vary the device off and on again to 
clear the error. Open the file or acquire 
the device again to continue. 


Messages: 


CPF5170 (Escape) 
CPF5422 (Escape) 


E-6 Application Display Programming V4R1 


Major Code 82 


Major Code 82—Open or acquire operation 
failed. 


Description: An attempt to open the display 
file or acquire the display device was not suc- 
cessful. The error may be recoverable or per- 
manent, but is limited to the specific display 
device. Recovery is unlikely until the problem 
causing the error has been corrected. 


Action: The following general actions can be 
taken for each 82xx return code. Other spe- 
cific actions are given in each return code 
description. You can either: 


¢ Continue processing without the device. 


e Release the device or close the file, 
correct the problem, and acquire the 
device or open the file again. A subse- 
quent operation could be successful if the 
error occurred because of some temporary 
condition such as the device being in use 
at the time. 


If the operation is still unsuccessful, try it 
again only a limited number of times. 
(The number of times should be specified 
in your program.) 


— If the attempted operation was an 
acquire operation, release the device 
and issue the acquire operation again. 


— If the attempted operation was an 
open operation, close the file and 
issue the open operation again. 


e End. 


Several return codes indicate that an error 
condition must be corrected by changing a 
value in the file. To change a parameter value 
for the file, use the Change Display File 
(CHGDSPF) or Override with Display File 


(OVRDSPF) command. 


Code _ Description/Action 


8281 Description: A system error condition 
was detected on an open or acquire oper- 
ation. The file may previously have been 
in error, or the file could not be opened 


due to a system error. 


8282 


8291 


Action: Determine the cause of the 
failure from the accompanying message. 
Check for any system operator messages 
indicating that additional corrective action 
must be performed. 


The display device may need to be varied 
off and then on again to clear the error. 
Your program can either: 


¢ Continue processing without the 
display device. 

e Release the device or close the file, 
correct the problem, and acquire the 
device or open the file again. 

e End. 


Messages: 


CPF4168 (Escape 
CPF4182 (Escape 
CPF4221 (Escape 
CPF5105 (Escape 
CPF5254 (Escape 
CPF5257 (Escape 


CPF5410 (Escape 
CPF5411 (Escape 
CPF5424 (Escape 
CPF5447 (Escape 
CPF5455 (Escape 


) 
) 
) 
) 
) 
)  CPF919E (Escape 


) 
) 
) 
) 
) 
) 


Description: The open or acquire opera- 
tion was not successful because the 
display device is unusable. This may 
occur because a cancel reply has been 
taken to an error recovery message for 
the device or because the display has 
been held by a Hold Communications 
Device (HLDCMNDEV) command. No 


operations should be issued to the device. 


Communications with the display cannot 
be resumed until the device has been 
reset to a varied-on state. 


Action: Close the display device file. If 
the device has been held, use the 
Release Communications Device 
(RLSCMNDEV) command to reset the 
device. If the device is in an error state, 
vary the device off and then on again. 
Once the device is reset, start normal 
operation by opening the display device 
file again. 


Messages: 


CPF4171 (Escape) 
CPF4354 (Escape) 
CPF5548 (Escape) 


Description: A permanent line error 


occurred on an open or acquire operation. 


The device has been marked unusable. 


8297 


82A6 


Action: Release the device in error or 
close the file. Vary the device off and on 
again to clear the error. Open the file 
again to continue. 


Messages: 


CPF4146 (Escape) 

CPF4179 (Escape) 

CPF4193 (Escape) 

CPF4291 (Escape) 

CPF5198 (Escape) 

CPF5260 (Escape) 

Description: The open or acquire opera- 
tion has ended abnormally due to an error 
condition detected at the display device 
that is not recoverable. An example of 
such an error is the user turning off the 
display device. 


Action: Release the device in error or 
close the file. The display device may 
need to be varied off and then on again to 
clear the error. Refer to the accompa- 
nying error message for additional infor- 
mation regarding the source of the specific 
error detected. Open the file or acquire 
the device again to continue. 


Messages: 


CPF4192 (Escape) 

CPF5047 (Escape) 

CPF5106 (Escape) 

CPF5140 (Escape) 

CPF5143 (Escape) 

CPF5199 (Escape) 

Description: The open or acquire opera- 
tion failed because the Systems Network 
Architecture (SNA) bind command was not 
successful. 


Action: Ensure that the display device 
with which your program is communicating 
is configured properly. Refer to the device 
response codes in the accompanying error 
message for additional information 
regarding the specific error detected. 


Messages: 


CPF4124 (Escape 
CPF4190 (Escape 
CPF5103 (Escape 
CPF5517 (Escape 


YS Ss YS HS 
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82A8 


82A9 


82AA 


82AB 


Description: The acquire operation was 
not successful because the maximum 
number of devices allowed for the display 
file has been reached. 


Action: Your program can recover by 
releasing a different device and issuing 
the acquire operation again. If more 
devices are needed, close your file and 
increase the MAXDEV value in the display 
file. 


Messages: 


CPF4745 (Escape) 
CPF5041 (Status) 
CPD4757 (Diagnostic) 


Description: The acquire operation was 
not successful because the requesting 
program device is not available. The 
requesting program device may not be 
available because your program is not 
running in an interactive job. 


Action: Your program can continue 
without the display, attempt to use a dif- 
ferent display device, or end. 


If your program needs to use the 
requesting program device, make sure 
that it runs in an interactive job. 


Messages: 


CPF4366 (Escape) 
CPF5381 (Escape) 


Description: The open or acquire opera- 
tion was not successful because the 
display device description was not found. 


Action: Your program can continue 
without the display, attempt to use a dif- 
ferent display device, or end. 


Verify that the name of the display device 
was correctly specified in the DEV param- 
eter on the CRTDSPF, CHGDSPF, 
CRTDEVDSP, or OVRDSPF command. 


Messages: 


CPF4103 (Escape) 
CPF4747 (Escape) 


Description: The open or acquire opera- 
tion was not successful because the 
display device was not varied on. 


Action: Your program can continue 
without the display, attempt to acquire a 
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82B3 


82EE 


different display device, or end. Vary on 
the display device and attempt the open 
or acquire operation again. 


If you want your program to continue with 
the same display, release the device or 
close the file, correct the problem, and 
acquire the device or open the file again. 


Messages: 


CPF4285 (Escape) 
CPF5333 (Escape) 


Description: The open or acquire opera- 
tion was not successful because the 
display device you are acquiring is in use 
in another process. 


Action: Wait for the display device to 
become available, then issue the acquire 
operation again. Otherwise, you may con- 
tinue other processing without the display, 
or end the program. 


You can use the Work with Configuration 
Status (WRKCFGSTS) command to deter- 
mine which job is using the display device. 


Consider increasing the WAITFILE param- 
eter of the CHGDSPF or OVRDSPF 
command to allow more time for the 
device to become available. 


Messages: 


CPF4109 (Escape) 
CPF4130 (Escape) 
CPF4282 (Escape) 
CPF5217 (Escape) 
CPF5332 (Escape) 


Description: An open or acquire opera- 
tion was attempted to a device that is not 
supported for a display file. 


Your program is attempting to acquire a 
device that is not a valid display device; or 
it is trying to acquire the requesting 
program device, but the requesting 
program device for the job is a commu- 
nications device, not a display device. 


Action: Your program can continue 
without the display, attempt to acquire a 
different display device, or close the file 
and end. 


Verify that the name of the display device 
was specified correctly on the CHGDSPF, 


82EF 


CRIDEVDSP, CRTDSPF, or OVRDSPF 
command. 


If your program was attempting to acquire 
the requesting program device, verify that 
your program is running in an interactive 
job so that the requesting program device 
is a display device. 
Messages: 

CPF4105 (Escape 

CPF4223 (Escape 


CPF4760 (Escape 
CPF5038 (Escape 


YS Hw NH 


Description: An open or acquire opera- 
tion was attempted for a device that the 
user is not authorized to or that is in 
service mode. 


Action: Your program can continue 
without the display, attempt to acquire a 
different display device, or end. 


If the operation was an open operation, 
close the file, correct the problem, and 

then issue the open operation again. If 
the operation was an acquire operation, 


82F8 


correct the problem and issue the acquire 
operation again. 


For authority errors, obtain authority to the 
device from your security officer or device 
owner. If the device is in service mode, 
the system service tools (SST) function is 
currently using the device. Wait until the 
device is available to issue the operation 
again. 


Messages: 


CPF4104 (Escape) 

CPF4186 (Escape) 

CPF5278 (Escape) 

CPF5279 (Escape) 

Description: Your program attempted an 
acquire operation to a device that is 
marked in error due to a previous error 
during an I/O or acquire operation. 


Action: Release the device or close the 
file, correct the previous error, and acquire 
the device or open the file again. 


Messages: 
CPF5293 (Escape) 
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Major Code 83 


Major Code 83-—Device error occurred (recov- 
erable). 


Description: An error occurred during an I/O 
operation, but the display device is still usable. 
Recovery within your program might be pos- 
sible. 


Action: The following general actions can be 
taken for each 83xx return code. Other spe- 
cific actions are given in each return code 
description. 


¢ Continue processing without the display 
device. 


¢ Correct the problem and continue pro- 
cessing with the display device. If the 
attempt to recover from the operation is 
unsuccesstul, try it again only a limited 
number of times. (The number of times 
should be specified in your program.) 


e End. 


Several return codes indicate that an error 
condition must be corrected by changing a 
value in the display file. To change a param- 
eter value for the file, use the Change Display 
File (CHGDSPF) or Override with Display File 
(OVRDSPF) command. 


Code _ Description/Action 


830B_ Description: Your program has 
attempted to issue an input or output 
operation either before the device was 
acquired or after it was released. 


Your program may have improperly 
handled a permanent device or acquire 
failed error. 


Action: Verify that your program tries no 
input or output operation with a display 
device that is not connected to the file and 
that return codes from acquire or I/O oper- 
ations are handled properly. 


Messages: 


CPD4079 (Diagnostic) CPF5070 (Escape) 
CPF4739 (Status) CPF5170 (Escape) 
CPF5067 (Escape) CPF5217 (Escape) 
CPF5068 (Escape) 
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831D 


831E 


Description: The operation just 
attempted by your program was rejected 
because a parameter was not valid, out of 
limits, or missing. 


Action: Your program can bypass the 
failing step and continue, or close the file 
and end. Refer to the accompanying 
message to determine what parameter 
was incorrect. Correct the error in your 
program before attempting to try the oper- 
ation again. 


Messages: 


CPF4912 (Notify 
CPF5002 (Notify 


CPF5012 (Notify 


CPF5021 (Notify 
CPF5218 (Escape 


CPF5303 (Escape 


) ) 
) ) 
CPF5008 (Notify) CPF5302 (Escape) 
) ) 
) ) 


CPF5014 (Notify CPF5398 (Escape 


Description: The operation just issued 
by your program was not valid or a combi- 
nation of operations that is not valid was 
specified. The error may have been 
caused by one of the following: 


e Either your program issued an opera- 
tion with an unrecognized code, or the 
operation specified by the code or 
DDS keyword is not supported by the 
display. 


¢ A combination of operations or 
keywords that is not valid was 
requested. 


e A user-defined data stream contained 
a command that is not valid for the 
display. 


Action: Your program can bypass the 
operation that is not valid and continue, or 
close the file and end. Refer to the 
accompanying message to determine why 
the operation was rejected. Correct the 
error in your program before attempting to 
try the failing operation again. 


Messages: 


CPF4564 (Escape 
CPF5005 (Notify 
CPF5011 (Notify 
CPF5039 (Notify 
CPF5045 (Notify 
CPF5051 (Notify 


CPF5055 (Notify) 
CPF5056 (Notify) 
CPF5059 (Notify) 
CPF5066 (Notify) 

) 


) 
) 
) 
) 
)  CPF5149 (Escape 
) 


831F 


8322 


832D 


Description: A length that is not valid 
was specified on the operation. 


On an output operation, your program has 
tried to send a data record having a length 
that exceeds the maximum record length 
allowed for the display device. The data 
has been truncated. 


Action: Issue the output operation again 
with a smaller output length. The record 
length for a non-field-level display file 
cannot exceed the display size. The 
record length for any display file must be 
no greater than 32 763 characters. 


Messages: 


CPF4010 (Diagnostic) 
CPF4078 (Diagnostic) 


Description: The attempted operation is 
not valid in the current state. Either a 
write operation was attempted while your 
program was not in the send state or a 
subfile operation was attempted when the 
subfile was not active. 


Action: Your program can bypass the 
operation that is not valid and continue, or 
close the file and end. Correct the 
sequence of operations in your program 
before attempting to run the job again. 


Messages: 


CPF5013 (Notify) 
CPF5060 (Notify) 


Description: Your program attempted an 
operation that is not valid when an invite 
operation is outstanding. Once you have 
issued an invite or get-no-wait operation, 
another invite operation cannot be issued 
for the same display device until the first 
invite has been completed by a read or 
read-from-invited-devices operation. 


Action: Issue an input operation to 
receive the data that was invited before 
issuing another invite operation. Other- 
wise, close the file and end. If a coding 
error in your program caused the error, 
correct the sequence of operations in your 
program. 


Messages: 
CPF5052 (Notify) 


8343 


83E0 


83E1 


83E8 


Description: An attempt was made to 
add another record to a subfile after the 
subfile was full. 


Action: Your program can clear the 
subfile, or continue without adding more 
records to the subfile. Otherwise, close 
the file and end. 


Increase the subfile length in the DDS 
statements. If a coding error in your 
program caused the error, correct your 
program. 


Messages: 
CPF5043 (Notify) 


Description: Your program attempted to 
issue an operation using a record format 
that was not defined for the display file, or 
omitted the record format name. 


Action: Check the name of the record 
format in your program to be sure it is 
correct. Then check that the record 
format is defined properly in the DDS for 
the file. 


Messages: 


CPF5022 (Notify) 

CPF5023 (Notify) 

CPF5053 (Notify) 

CPF5054 (Notify) 

Description: An error occurred during an 
I/O operation. The requesting program 
device was set to automatically disconnect 
your program. The same user signed on 
to the same display device, so the 
program was started up again. The 
display was cleared of any data present 
when the error occurred. 


Action: Branch to a normal starting point 
in your program and rewrite the display. 
There is no need to perform a close or 
open operation on the display files that 
were active when the error occurred. 


Messages: 
CPF509F (Notify) 


Description: Your CL program issued an 
End Receive (ENDRCV) command when 
there is no outstanding read-with-no-wait 
operation. 
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Action: Your program can issue an 
output operation to continue sending, 
issue an input operation to begin 
receiving, or close the file and end. 
Correct the error in your program before 
attempting to repeat the failing operation. 
Messages: 
CPF4910 (Notify) 83F8 

83F6 Description: Your program sent data to 

the display that is not valid. The data type 

may not be correct for the field in which it 

is used. 


Action: Check the name of the record 
format in your program to be sure it is 
correct. Verify that the data definition 
statements in your program match the 
output record defined in the DDS for the 
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file. Correct the error in your program 
before attempting to repeat the failing 
operation. 


Messages: 


CPF5063 (Notify) 
CPF5216 (Escape) 
CPF5301 (Escape) 


Description: Your program attempted an 
I/O operation to a device that is marked in 
error due to a previous error during an I/O 
or acquire operation. 


Action: Release the device or close the 
file, correct the previous error, and acquire 
the device or open the file again. 


Messages: 
CPF5293 (Escape) 


Appendix F. Edit Codes 


OS/400 Edit Codes 


The following table summarizes the functions pro- 
vided by OS/400 edit codes. 


Table F-1 (Page 7 of 2). Summary Chart for OS/400 Edit Codes 

Sign Blank l J 

Displayed | Value of Value of Value of 

Decimal When QDECFMT QDECFMT QDECFMT Leading 

Edit Commas! Points! Negative | System System System Zero 
Codes | Displayed Displayed | Value Value Value Value Suppressed 
1 Yes Yes No sign .0O or 0 ,00 or 0 0,00 or 0 Yes 
2 Yes Yes No sign Blanks Blanks Blanks Yes 
3 Yes No sign .0O or 0 ,00 or 0 0,00 or 0 Yes 
4 Yes No sign Blanks Blanks Blanks Yes 
A Yes Yes CR .00 or 0 ,00 or 0 0,00 or 0 Yes 
B Yes Yes CR Blanks Blanks Blanks Yes 
Cc Yes CR .00 or 0 ,00 or O 0,00 or 0 Yes 
D Yes CR Blanks Blanks Blanks Yes 
J Yes Yes (Minus) .00 or 0 ,00 or 0 0,00 or O Yes 
K Yes Yes -(Minus) Blanks Blanks Blanks Yes 
L Yes —(Minus) .00 or 0 ,00 or 0 0,00 or 0 Yes 
M Yes -(Minus) Blanks Blanks Blanks Yes 
N Yes Yes (Minus) .00 or 0 ,00 or 0 0,00 or 0 Yes 
oO Yes Yes -(Minus) Blanks Blanks Blanks Yes 
P Yes —(Minus) .00 or 0 ,00 or 0 0,00 or 0 Yes 
Q Yes -(Minus) Blanks Blanks Blanks Yes 
Y2 Yes 
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Table F-1 (Page 2 of 2). Summary Chart for OS/400 Edit Codes 


Sign Blank I J 
Displayed | Value of Value of Value of 
Decimal When QDECFMT QDECFMT QDECFMT Leading 
Edit Commas! Points! Negative System System System Zero 
Codes | Displayed Displayed | Value Value Value Value Suppressed 
Z3 Yes 
Notes: 


1. The QDECFMT system value determines the decimal point character (period in U.S. usage), the character 
used to separate groups of three digits (comma in U.S. usage), and the type of zero suppression (depending 
on comma and period placement). For more information on the QDECFMT system value, see the Work Man- 
agement book. 


2. The Y edit code suppresses the farthest left zero of a date field that is three to six digits long, and it sup- 
presses the two farthest left zeros of a field that is seven positions long. The Y edit code also inserts slashes 
(/) between the month, day, and year according to the following pattern: 


nn/n 
nn/nn 
nn/nn/n 
nn/nn/nn 
nnn/nn/nn 


If the DATE keyword is specified with EDTCDE(Y), the separator character used is the job attribute, DATSEP. 
The slash (/) is the default DATSEP. If, at file creation time, DATFMT is JUL (Julian), the date is normally 
formatted as nn/nnn and EDTCDE(Y) is not valid. 


3. The Z edit code removes the sign (plus and minus) from a numeric field. The sign of the units position is 
changed to a hexadecimal F before the field is written. 


Note: Edit code X can be specified but has no other effect on the display file and is ignored for 


effect on display files and is ignored. The AS/400 
system hardware operates with a preferred sign of 
F, which is equivalent to using edit code X. Edit 

code X causes a blank keyboard shift (position 35) 


all other processing. The display length of the 
field is determined by the keyboard shift and not 


by edit code X (the default numeric-only Y attri- 


to default to numeric only (attribute Y), but has no 


F-2 Application Display Programming V4R1 


bute may add 1 position to the field for decimals). 


The date separator character is determined by the 
job attribute DATSEP. In this figure, QDECFMT is 
assumed to equal x, and DATSEP is assumed to 

equal /. 


Examples of Editing Using 
OS/400 Edit Codes 


The following table shows valid edit codes with 
examples of unedited source data and edited 
output. Zero suppression and decimal characters 
are determined by the system value QDECFMT. 


Table F-2. Valid Edit Codes, Source Data, and Edited Output 


Positive Positive Negative Negative Zero Zero 
Number— Number-— Number-— Number-— Balance— Balance— 
Two No Three No Two No 
Decimal Decimal Decimal Decimal Decimal Decimal 

Edit Codes| Positions Positions Positions! Positions! Positions! Positions! 

Unedited 1234567 1234567 XXXX.125— XXXX.125— XXXXXX XXXXXX 

1 12,345.67 1,234,567 125 125 .00 0 

2 12,345.67 1,234,567 125 125 

3 12345.67 1234567 125 125 .00 0 

4 12345.67 1234567 125 125 

A 12,345.67 1,234,567 .125CR 125CR .00 0 

B 12,345.67 1,234,567 .125CR 125CR 

C 12345.67 1234567 .125CR 125CR .00 0 

D 12345.67 1234567 .125CR 125CR 

J 12,345.67 1,234,567 .125- 125- .00 0 

K 12,345.67 1,234,567 .125- 125- 

L 12345.67 1234567 .125- 125- .00 0 

M 12345.67 1234567 .125- 125- 

N 12,345.67 1,234,567 -.125 -125 .00 0 

oO 12,345.67 1,234,567 -.125 -125 

P 12345.67 1234567 -.125 -125 .00 0 

Q 12345.67 1234567 -.125 -125 

Y2 123/45/67 123/45/67 0/01/25 0/01/25 0/00/00 0/00/00 

Z3 1234567 1234567 125 125 

Notes: 


1. The x represents a blank. 


2. The Y edit code suppresses the farthest left zero of a date field that is three to six digits long, and 
it suppresses the two farthest left zeros of a field that is seven positions long. For more informa- 


tion, see the second footnote in Table F-1 on page F-1. 


3. The Z edit code removes the sign (plus or minus) and suppresses leading zeros. 
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User-Defined Edit Codes 


You can define five edit codes to provide more 
editing function than is available with the OS/400 
edit codes, and to handle common editing func- 
tions that would otherwise require the use of an 


You can define your own edit codes using the 
Create Edit Description (CRTEDTD) command. 


edit word. 


Table F-3. IBM-Supplied Edit Descriptions 

QEDIT5 Edit QEDIT6 Edit QEDIT7 Edit QEDITS Edit QEDIT9 Edit 
Description Codes! Codes! Codes! Codes! Codes! 
Integer XXX,XXX,XXX,XXX,XXO. XXX,XXX,XXX,XXX,XXO XXX,XXX,XXX,XXX, XOX XXX,XXX,XXX,XXX,XOX Oxx-XX-XX 
mask 
Decimal . (period) . (period) . (period) . (period) . (period) 
point 
Fraction XXXXXXXXX XXXXXXXXX XXXXXXXXX XXXXXXXXX None 
mask 
Fill character x x x x 
Floating cur- None None None $ None 
rency 
symbol 
Zero Replace with fill Replace with fill Normal editing Normal editing Normal editing 
balance character character rules rules rules 
Negative CR - (minus sign) - (minus sign) - (minus sign) None 
status 
Positive DR None None None None 
status 
Left constant None None $ None None 
Right con- None x* None None None 
stant 
1 The x represents a blank. 


An edit description contains the following items: 


Integer mask 
Describes the editing of the integer 
portion of a field. All characters except 
blank, zero, and ampersand (&) are 
treated as constants: 

e Blank means to replace the blank 
with a digit if zero suppression has 
ended; otherwise, replace the 
blank with the fill character. 

e The zero to the farthest left means 
to replace the zero with a digit and 
end zero suppression. All other 
zeros are treated as constants. 

e Ampersand means to replace the & 
with a blank. 

Decimal point 
Defines what character is used as the 
decimal point. By default, a period (.) 
is used. 
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Fraction mask 
Describes the editing of the fraction 
portion of a field. Ampersand is the 
same as for the integer mask. All 
zeros are treated as constants and all 
blanks are replaced with digits (no fill 
character is used). 

Fill character 
Defines what character is used in each 
position of a result that is zero- 
suppressed. By default, a blank is 
used. 

Floating currency symbol 
Defines the floating currency symbol to 
be used to edit the field. 

Zero balance 
Specifies how zero values are to be 
edited. They can be edited using the 
fill character or the integer and fraction 
masks. 


Negative status 
Defines the characters that are to 
follow the edited result of a field if the 
field is negative. 

Positive status 
Defines the characters that are to 
follow the edited result of a field if the 
field is positive or zero. 

Left constant 
Defines a constant that is to be the 
portion to the farthest left of the edited 
result of a field. 

Right constant 
Defines a constant that is to be the 
portion to the farthest right of the 
edited result of a field. 


Using User-Defined Edit Codes 


The following rules apply to using edit 
descriptions. These rules are affected by the 
length and decimal positions of the field being 
edited. 


e The field to be edited is aligned by the integer 
and fraction masks. 

e The entire integer mask is not always used. 
The integer mask is truncated on the left side 
immediately before the farthest left significant 
digit or farthest left, or forced, zero. 

e¢ The decimal point immediately follows the 
integer mask and the fraction mask imme- 
diately follows the decimal point. If no 
decimal point is used, the fraction mask imme- 
diately follows the integer mask. 

e The entire fraction mask is not always used. 
The fraction mask is truncated on the right 
side immediately following the farthest right 
significant digit. 

e The width of the edited result is equal to the 
total of the following: 

— Length of left constant 
— Length of floating currency symbol 


— Length of truncated integer mask 

— Length of decimal point (which is always 1 
unless no decimal point is used) 

— Length of truncated fraction mask 

— Length of negative or positive status value 
(whichever is longer) 


Note: If the text you specify for negative 
status is a different length than the one for 
positive status, the CRTEDTD command 
pads the shorter value with blanks. This 
makes the shorter value equal in length to 
the longer value. 
— Length of right constant 
e If either the integer mask or fraction mask 

does not contain enough digit replace charac- 

ters for the field to be edited, the field is not 

edited and is ignored. 


Example of a User-Defined Edit 
Code 


The following Create Edit Description (CRTEDTD) 
command shows how to create an edit description 
to edit a numeric field and indicate if the value is a 
credit or debit (x indicates a blank): 


CRTEDTD EDTD(5) INTMASK('xxx,xxx,xXx') 
FRACMASK('xxxx') NEGSTS('DEBITx') 
POSSTS('CREDIT') LFTCNS('$') 
RGTCNS ('xBx*') 


The field that uses the previous edit description 
contains the value 001234 and has two decimal 
positions. The edited field looks like this: 


$xx12.34CREDITx** 


Note that when you create an edit description, you 
specify only the number (5, 6, 7, 8, or 9) that is 
associated with the edit code. The system auto- 
matically affixes QEDIT to the number you specify. 
(In the preceding example, EDTD(5) was speci- 
fied. This would then be QEDIT5.) 
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Appendix G. System/36-Compatible Display Data 


Management 


This appendix describes how to use OS/400 
display data to provide System/36-compatible 
functions. Additional information on System/36 
compatibility can be found in the DDS Reference. 


In order to migrate System/36 applications that 
use display devices, OS/400 display data manage- 
ment has functions that allow the operating 
system to work like System/36 work station data 
management. The level of compatibility with the 
System/36 depends on the following: 


e The User Display Management 
(USRDSPMGT) keyword 


This keyword is automatically put in the DDS 
source when the $SFGR utility or the Create 
System/36 Display File (CRTS36DSPF) CL 
command converts SFGR source to DDS 
source. Specifying this keyword indicates that 
the System/36 work station data management 
function is to be used instead of OS/400 
display data management functions. 


For example, the USRDSPMGT keyword 
specifies that the cursor is positioned as it is 
on the System/36. If the USRDSPMGT 
keyword is not specified, the cursor is posi- 
tioned according to the OS/400 display data 
management rules. 


¢ The programming language used to write the 
program 


To get application-level System/36 compat- 
ibility, the programs must be written in 
System/36-compatible RPG II or 
System/36-compatible COBOL. 


For example, if a program is written in a 
System/36-compatible language, the file status 
codes set by the high-level language and 
return codes set by data management are the 
same as the System/36. If a program is not 
written in a System/36-compatible language, 
the file status codes and return codes are the 
AS/400 values. 


e The environment where the application runs 


To get environment-level System/36 compat- 
ibility, the programs must run in the System/36 
environment. 
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For example, if an application running in the 
System/36 environment uses the MSGID DDS 
keyword to display the message from a user 
message file, the message file used is the 
message file specified on the USER1 param- 
eter of the MEMBER OCL statement. If this 
same application is not run in the System/36 
environment, the message file used is a 
message file named USR1 in the job’s library 
list. 


The remainder of this appendix contains a section 
for each display data management topic you may 
need to know about if you are interested in S/36 
compatibility. Where appropriate, each topic con- 
tains the following information: 


¢ How the System/36 supports the function. 
More information on the System/36 functions 
can be found in the following manuals: 


— System/36 Creating Displays: Screen 
Design Aid and System Support Program. 


— System/36 Concepts and Programmer's 
Guide. 


¢ How the default OS/400 display data manage- 
ment supports the function. 


¢ How to get the System/36-compatible function 
with OS/400 display data management, 
including which of the three level-of- 
compatibility items previously listed is required 
to get the compatible function. 


Clearing Lines on the Display 


When a System/36 application writes the first 
record in a job, System/36 work station data man- 
agement clears the display before displaying the 
application data. The System/36 function is pro- 
vided on the AS/400 system for the first write 
operation in a System/36-environment job if the 
program is written in a System/36-compatible lan- 
guage or the display file contains the 
USRDSPMGT keyword. The System/36 Environ- 
ment Programming book describes starting and 
ending a System/36-environment job. 
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OS/400 display data management normally clears 
the display when a display file is opened; 
System/36 work station data management does 
not. The System/36 function is provided by the 
OS/400 operating system for programs written in a 
System/36-compatible language or that open a 
display file that specifies the USRDSPMGT 
keyword. 


Applications can clear all or just parts of the 
display by using the clear line (CLRL) keyword. 
The CLRL keyword is automatically put in the 
DDS source when the System/36 environment 
converts the SFGR source to DDS. The value 
generated for the number of lines to clear is based 
on the value in columns 19 and 20 of the SFGR S$ 
specification. 


Because some of the OS/400 and 
System/36-compatible display-clearing functions 
are different, the following DDS keywords cannot 
be used in display files that specify the 
USRDSPMGT keyword: 


e ERASE 

e PUTRETAIN 
e KEEP 

e ASSUME 


Also, the OVERLAY keyword is ignored for pro- 
grams written in a System/36-compatible language 
and for display files that specify the USRDSPMGT 
keyword. 


Input Data for Display File 
Records 


On the System/36, only one record with input 
fields can be displayed. For example, if an appli- 
cation on the System/36 writes record REC1 and 
then record REC2, only the last record written 
(REC2) has input-capable fields. When REC1 is 
written, the input fields defined by REC1 are input- 
capable. When REC2 is written, REC1 fields are 
then no longer input-capable, and the input fields 
defined by REC2 are input-capable. 


With the default OS/400 display data management 
support, many different records with input fields 
can be displayed at the same time. For example, 
record REC1 (which occupies lines 1 through 12) 
and record REC2 (which occupies lines 21 
through 24) can be displayed at the same time. 
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The application program can read data from either 
record. Only the data for the input-capable fields 
defined by the specific record is returned. In the 
previous example, if the application program 
needs to get all the data from all the input-capable 
fields on the display, the application has to issue 
two read operations: one for REC1 and one for 
REC2. 


OS/400 display data management allows only one 
record with input fields for programs written in a 
System/36-compatible language or for display files 
that specify the USRDSPMGT keyword. 


Input Data from the Work Station 
Controller 


The System/36 work station controller returns the 
data for all input-capable fields. With the default 
OS/400 display data management support, the 
work station controller returns only data from the 
display for the input-capable fields that the display 
station operator has changed. 


OS/400 display data management provides the 
System/36 function with the Modified Data Tag 
(MDT) value of the DSPATR DDS keyword. The 
DSPATR(MDT) keyword is automatically put in the 
DDS source for every input-capable field when the 
System/36 environment converts SFGR source to 
DDS. This keyword sets on an indicator in the 
work station controller that makes the work station 
controller act as if the field with DSPATR(MDT) 
was changed by the display station operator. 
Because this keyword is specified for all input- 
capable fields, all the input data is returned to the 
system and to the program when the program 
issues a read operation. 


Self-Check 


On System/36, if a field specifies modulus 10 or 
modulus 11 self-checking (column 30 of SFGR D 
specification), the work station controller verifies 
that valid data is entered into the field. If a display 
station operator enters an incorrect modulus 10 or 
modulus 11 number for a field, the work station 
controller displays a blinking four-digit error code, 
and the user must enter data into the field again. 


OS/400 display data management support for self- 
check, which uses the CHECK(M10) and 


CHECK(M11) DDS keywords, verifies that the field 
has a valid modulus 10 or modulus 11 number 
when you press the Enter key or another function 
key. This verification is used in place of issuing 
an error message as you type data into the field. 

If the CHECK(M10F) or CHECK(M11F) keyword is 
specified, the workstation controller verifies that 
valid data is entered into the field as described in 
the previous paragraph. 


If a display file contains the CHECK(M10) or 
CHECK(M11) DDS keyword and also the 
USRDSPMGT keyword, OS/400 display data man- 
agement, like the System/36, issues an error 
message as you type the data. The DDS 
keywords CHECK(M10F) and CHECK(M11F) are 
not allowed with the USRDSPMGT keyword. 


Return Input 


System/36 work station data management has 
support to indicate to an application program 
whether any fields on the display have been 
changed by the display station operator. To use 
this support, the SFGR source must specify N for 
return input (column 22) in the SFGR S specifica- 
tion. If N is specified and the user does not 
change any fields on the display, all blanks are 
received as input data for a read operation. 


OS/400 display data management provides the 
System/36 support. If the CHANGE keyword is 
specified at the record level without a response 
indicator in a display file that specifies the 
USRDSPMGT keyword, and the program doing 
the read operation is written in a 
System/36-compatible language, the program 
receives a blank record when the display station 
operator does not change any data on the display. 
The CHANGE keyword is automatically put in the 
DDS source when SFGR source is converted to 
DDS by the System/36 environment if N is speci- 
fied for return input. 


Erase Input Fields 


On System/36, if a program writes a record to the 
display and the erase-input-fields function 
(columns 31 and 32 of the SFGR S specification) 
is enabled for the record, the input fields on the 
display are erased, but the specified record is not 
sent to the display. For example, if a program 


writes record REC1 to the display and then writes 
record REC2 to the display (where REC2 has the 
erase-input-fields function enabled), all the input 
fields defined by REC1 are erased and REC2 is 
not sent to the display. 


OS/400 display data management follows the 
System/36 handling of erase-input-fields when the 
program is written in a System/36-compatible lan- 
guage, the USRDSPMGT keyword is specified, 
and the ERASEINP keyword is enabled for the 
record. 


On System/36, if a program writes a record to the 
display and the erase-input-fields and put-override 
functions are both enabled for the record, the 
input fields on the display are erased, and the put- 
override data for the specified record is sent to the 
display. 


OS/400 display data management follows the 
System/36 handling of erase-input-fields when the 
program is written in a System/36-compatible lan- 
guage, the USRDSPMGT keyword is specified, 
and the ERASEINP and PUTOVR keywords are 
enabled for the record. 


Display Attributes 


Some fields do not have beginning display attri- 
butes on the System/36. A field has a beginning 
display attribute only if one or more of the fol- 
lowing is true: 


e The field is input-capable. 


e The output data is based on an indicator 
(column 23-24 of SFGR D specification). 


e The field specifies a display attribute (such as 
high intensity, blink, reverse image, underline, 
or column separators). 


e The field appears on a row that is not cleared 
by the record. 


To provide application compatibility with the 
System/36, OS/400 display data management 
follows the System/36 rules to determine if a field 
should have a beginning attribute when the 
USRDSPMGT keyword is specified in a display 
file. Also, if a field does not have a beginning 
attribute and the OVRATR keyword is specified on 
the field, the OVRATR keyword is ignored (no field 
attribute is sent). 
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On the System/36, some fields do not have 
ending display attributes. A field has an ending 
attribute only if one or more of the following is 
true: 


e The field is input-capable. 


e The output data is based on an indicator 
(columns 23-24 of SFGR D specification). 


e The field specifies a display attribute (such as 
high intensity, blink, reverse image, underline, 
or column separators). 


OS/400 display data management follows the 
System/36 rules to determine if a field should 
have an ending attribute when the USRDSPMGT 
keyword is specified in a display file. 


Positioning the Cursor 


System/36 uses the following rules to determine 
where the cursor should be positioned when a 
record is displayed: 


1. The cursor is positioned to the first input field 
(defined by the SFGR source statements) that 
has an indicator specified for the position- 
cursor attribute, has this indicator set on, and 
where one of the following conditions is true: 


e This field does not have the protect attri- 
bute specified (columns 37 and 38 of the 
SFGR D specification). 


e This field has an indicator specified for the 
protect attribute, but the indicator is off. 


e This field has an unoptioned-protect attri- 
bute specified (columns 37 or 38 of the 
SFGR D specification is Y or N). 


2. If the cursor is not positioned by rule 1, a 
check is made for fields with an unoptioned- 
position-cursor attribute (columns 32 or 33 of 
the SFGR D specification is Y). If there is a 
field with an unoptioned-position-cursor attri- 
bute, the cursor is positioned to this field. 


3. If the cursor is not positioned by rule 1 or 2, 
the cursor is positioned to the first input field 
(as defined by the SFGR source statements) 
that does not have an unoptioned-protect attri- 
bute (columns 37 or 38 of the SFGR D spec- 
ification are blank). 
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4. If the cursor is not positioned by any of the 
previous rules, the cursor is positioned to the 
upper-left-hand corner of the display. 


OS/400 display data management positions the 
cursor following the System/36 rules for display 
files that have the USRDSPMGT keyword speci- 
fied. 


Displaying Messages 


On System/36, fields can be defined that have 
message text automatically inserted into the field 
when a record is displayed. System/36 work 
station data management retrieves the message 
text defined for the field and supplies the message 
text as output data for the field. To display 
message text, System/36 applications must 
specify the following: 


e¢ M for constant type (column 56 of SFGR D 
specification). 


¢ The message identification code (MIC) 
(columns 57 through 60 of SFGR D specifica- 
tion or output data supplied by the program). 


e The message member identifier (columns 61 
and 62 of SFGR D specification or output data 
supplied by the program). 


OS/400 applications can display messages in a 

variety of different ways. For information on dis- 
playing messages, see “Creating and Displaying 
Your Own Messages” on page 8-1. 


To provide application compatibility with 
System/36, the MSGID keyword can be used to 
display messages. The MSGID keyword is auto- 
matically generated by the System/36 environment 
if M is specified for constant type in the SFGR D 
specification. 


Either of the following formats can be used to 
display messages that follow the System/36 con- 
ventions for sending messages: 


MSGID(message-identifier message-file) 


MSGID(USR message-identification-code message-file) 


Message-identifier consists of two parts: a 
message prefix and a message-identification-code 
(MIC). If an application uses the first format of the 
MSGID keyword, the three-character message 
prefix should be the first three characters of the 


seven-character message-identifier. If an applica- 
tion uses the second format of the MSGID 
keyword, the prefix does not need to be provided. 
The prefix is already specified as USR in the 
MSGID keyword. 


The message-identification-code parameter speci- 
fies the four-character message ID of the 
message to be displayed. 


For more information on specifying display file 
message-identifiers, see the DDS Reference. 


The message-file parameter identifies the 
message file that contains the message to be dis- 
played. For System/36 compatibility, this param- 
eter can be specified in one of two formats. 


The first format for specifying the message-file 
parameter is in a two-character field-name. The 
field-name must exist in the same record as the 
MSGID field, and the field must be defined as a 
character field with usage H (hidden), P (program- 
to-system), B (both), or O (output-only). The field 
identified by field-name indicates the message file 
that the System/36 environment uses to display a 
message. The values allowed for the field are: 


Table G-1. Message Files for MSGID 


Value of 


Field-Name Message File Used 


U1 Message text from the 
message file specified on 
USER1 parameter on 
MEMBER OCL statement. 


U2 Message help text from 
the message file specified 
on USER2 parameter on 
MEMBER OCL statement. 


P1 Message text from the 
message file specified on 
PROGRAM1 parameter on 
MEMBER OCL statement. 


P2 Message help text from 
the message file specified 
on PROGRAM2 parameter 
on MEMBER OCL state- 
ment. 


M1 Message text from 
IBM-supplied message file 
##MSG1. 


M2 Message help text from 
IBM-supplied message file 
##MSG1. 


The second format for specifying the message-file 
parameter is a special value. The following 
special values can be specified for the message 
file: 


Table G-2 (Page 1 of 2). Message Files for 
MSGID 


Special Message File Used 

Value 

*“USRI1 Message text from message file 
specified on USER1 parameter 
on MEMBER OCL statement. 

*“USR2 Message help text from 
message file specified on 
USER2 parameter on MEMBER 
OCL statement. 

*PGM1 Message text from message file 


specified on PROGRAM1 
parameter on MEMBER OCL 
statement. 
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Table G-2 (Page 2 of 2). Message Files for 
MSGID 


Special Message File Used 

Value 

*PGM2 Message help text from 
message file specified on 
PROGRAN2 parameter on 
MEMBER OCL statement. 

*SYS1 Message text from IBM-supplied 
message file ##MSG1. 

*SYS2 Message help text from 


IBM-supplied message file 
##MSG1. 


The following are considerations you should be 
aware of when using the System/36-compatible 
functions of the MSGID keyword: 


e lf afield name or a special value is specified, 
the processing done by OS/400 display data 
management depends on the environment 
where the application runs. For example, if 
the application is run in the System/36 envi- 
ronment, *USR1 indicates to use the message 
file identified by the USER1 parameter on the 
MEMBER OCL statement. If the same appli- 
cation is not run in the System/36 environ- 
ment, “USR1 indicates to use message file 
USR1. 


e If the message is to be displayed and it only 
has message help, the message help is dis- 
played. 


e If the message help is to be displayed but the 
message has no message help, only the 
message is displayed. 


e If the message text to be displayed is longer 
than the length of the output field, the 
message text is truncated to the length of the 
output field. If the message text to be dis- 
played is shorter than the length of the output 
field, the message text is padded with blanks. 


e lf the message identifier contains any charac- 
ters that are not valid (valid characters are 0-9 
and A-F), the message text displayed is the 
message identifier followed by the two- 
character message file identifier. 


e lf the message identifier or the message file is 
not found, the message text displayed is the 
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message identification code followed by two 
question marks (?7). 


e The following DDS keywords cannot be speci- 
fied on a field with the MSGID keyword: 


DFT 
DFTVAL 
FLTFIXDEC 
FLTPCN 
MSGCON 


Put Override 


On System/36, if the put-override option is 
enabled (columns 33 and 34 of SFGR S specifica- 
tion) and the number of lines to clear (columns 19 
and 20 of SFGR S specification) is specified, the 
number of lines to clear is ignored. System/36 
work station data management does not clear the 
display when the put-override option is enabled. 
OS/400 display data management also has 
support to ignore the clear function (CLRL 
keyword) for records that have the put-override 
option (PUTOVR keyword) enabled. This support 
is used for programs written in a 
System/36-compatible language or using a display 
file that specifies the USRDSPMGT keyword. 


On System/36, if the put-override option is 
enabled, no input-field definitions are sent to the 
display. Input-field definitions contain information 
such as length of the input-field, mandatory-fill 
attribute, mandatory-enter attribute, 
modified-data-tag attribute, and protected input- 
field attribute. If there are input fields currently on 
the display, these fields remain input-capable. 
The default OS/400 display data management 
support sends input-field definitions when the put 
override option is enabled. OS/400 display data 
management provides the System/36 function of 
not sending input-field definitions to the display 
when the put-override function is enabled and the 
record to be displayed is in a display file that 
specifies the USRDSPMGT keyword. If the appli- 
cation uses the System/36 function of not sending 
input-field definitions to the display when the put- 
override function is enabled, attributes that are 
defined by the input-field definitions cannot be 
changed when put-override is enabled. For 
example, the protected input-field attribute 
(DSPATR(PR)) is ignored when put-override is 
enabled, because the input-field definitions are not 
sent to the display. 


On System/36, the put-override option can be 
specified for records that are currently displayed 
and for records that are not currently on the 
display. For example, if record REC1 is currently 
displayed and the application program issues a 
write operation with the put-override function 
enabled for record REC2, the request to display 
record REC2 is processed as a put-override 
request. The default support in OS/400 display 
data management supports the put-override func- 
tion only for records that are currently displayed. 
For example, if record REC1 is currently displayed 
and the application program issues a write opera- 
tion with the put-override function enabled for 
record REC2, the put-override function is ignored 
and the request to display record REC2 is pro- 
cessed as if the PUTOVR keyword was not 
enabled. If the display file specifies the 
USRDSPMGT keyword, OS/400 display data man- 
agement provides the System/36 function of 
allowing the put-override function even if the 
record is not currently displayed. 


During an override operation, OS/400 display data 
management may ignore help specifications con- 
tained in the record format that is displayed by the 
application program. This occurs if the 
USRDSPMGT keyword is used. If the Help 
Cleared (HLPCLR) keyword is also specified on 
the record format, no online help is available. 


Handling Signed Numeric Data 


System/36 does no checking when incorrect data 
(data other than O through 9) is specified for a 
signed numeric field on a write operation. For 
example, if the data in a signed numeric field is 
character data, the character data is displayed. 
The default support in OS/400 display data man- 
agement is to replace any incorrect signed 
numeric data with nulls when the field is dis- 
played. OS/400 display data management sup- 
ports the System/36 function when the 
USRDSPMGT keyword is specified in the display 
file. 


System/36 also does no checking when a read 
operation returns incorrect data for a signed 
numeric field. For example, if the data returned 
for a signed numeric field is character data, the 
character data is passed to the application 
program. The default support in OS/400 display 


data management replaces any incorrect signed 

numeric data with zeros before the data is given 

to the application program. OS/400 display data 
management supports the System/36 function for 
programs written in a System/36-compatible lan- 

guage. 


On System/36, if zeros are entered in a signed 
numeric field and the field-minus key is used to 
exit the field, a value of negative zero is returned 
to the application program. The default support in 
OS/400 display data management returns zeros to 
the application instead of negative zero. OS/400 
display data management supports the System/36 
function for programs written in a 
System/36-compatible language or using a display 
file that specifies the USRDSPMGT keyword. 


Function Keys 


On System/36, application programs can receive 
control when a function key is pressed. To use 
this support, the application must enable the 
desired function key in the SFGR source and the 
program must indicate that it can process the 
function key. 


The default OS/400 display data management 
support does not allow a program not written in a 
System/36 compatible language to indicate which 
function keys the program can process. The func- 
tion keys that are enabled in the DDS for the 
display file are the function keys that OS/400 
display data management passes to the program 
to handle. 


OS/400 display data management supports the 
System/36 function of a program indicating which 
function keys it can process for programs written 
in a System/36-compatible language. See the 
appropriate System/36-compatible language 
manual for information on enabling function-key 
handling in a program. 


Help Key Considerations 


The HELP and HLPRTN DDS keywords are used 
to indicate what processing should be done by the 
system when the Help key is pressed. The HELP 
keyword indicates that the application wants the 
Help key enabled. The HELP keyword is auto- 
matically put in the DDS source when SFGR 
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source is converted to DDS by the System/36 
environment. 


The HLPRTN keyword indicates that the applica- 
tion program wants to process the Help key when 
the display station operator presses the Help key. 
When the Help key is enabled in the SFGR key 
mask (columns 64 through 79 of the SFGR S 
specification) the HLPRTN keyword is put in the 
DDS source when the System/36 environment 
converts SFGR source to DDS. 


If the HELP and HLPRTN keywords are not speci- 
fied and the display station operator presses the 
Help key, a message is displayed by OS/400 
display data management indicating that the Help 
key is not allowed. 


If the USRDSPMGT and HELP keywords are 
specified, the HLPRTN keyword is not specified, 
and the display station operator presses the Help 
key, OS/400 display data management uses the 
following rules to determine how the Help key is 
be processed: 


1. If the Help key is pressed when a message is 
being displayed, the message help for the 
message is displayed. 


2. If the Help key is not processed by rule 1 and 
there is application help defined for the record, 
the application help for the record is dis- 
played. 


3. If the Help key is not processed by rules 1 or 
2, an error message is displayed indicating 
that the key is not allowed. 


If the USRDSPMGT, HELP, and HLPRTN 
keywords are specified and the display station 
operator presses the Help key, OS/400 display 
data management uses the following rules to 
determine how the Help key is be processed: 


1. If the application program has indicated that it 
can process the Help key, an indication is 
returned to the application program that the 
Help key was pressed. 


2. If the Help key is not processed by rule 1 and 
the Help key is pressed when a message is 
being displayed, the message help for the 
message is displayed. 


3. If the Help key is not processed by rules 1 or 
2 and there is application help defined for the 
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record, the application help for the record is 
displayed. 


4. If the Help key is not processed by rules 1, 2 
or 3, an error message is displayed indicating 
that the key is not allowed. 


Using Command Keys to Exit 
Application Help 


On System/36, if application help is displayed and 
the display station operator presses a command 
key to exit application help, an indication of what 
command key was pressed is given to the applica- 
tion program. To use this support, the application 
must enable the desired command key on the 
display where the Help key is pressed, and the 
key must be enabled on the application help 
display. If the display file containing application 
help specifies the USRDSPMGT keyword, OS/400 
display data management returns the indication of 
what command key was pressed to exit applica- 
tion help. If the command key was not specified 
on both the application record and the help record, 
the message, Function Key not Allowed is dis- 
played. 


On System/36, if application help is displayed and 
the display station operator presses a command 
key to exit application help, the data from the 
display where the Help key is pressed is returned 
to the application program. To use this support, 
the application must indicate restore yes (columns 
47 and 48 of the SFGR H specification) on the 
display where the Help key is pressed. OS/400 
display data management returns the data from 
the display where the Help key is pressed if the 
display file containing application help specifies 
the USRDSPMGT keyword. 


Cancel-Invite Operation 


On System/36, if a program issues a cancel-invite 
operation and data has already been received by 
the system (for example, the display station oper- 
ator pressed the Enter key before the cancel-invite 
was issued), the data is lost and the application is 
not notified. 


The default OS/400 display data management 
support causes the cancel-invite operation to fail if 
the data is available. Message CPF4737 and 


return code 0412 are sent to the application 

program. The application can check the return 
code and issue a read operation to receive the 
data that was returned from the display station. 


OS/400 display data management supports the 
System/36 function and does not send message 
CPF4737 or set the return code for programs 
written in a System/36-compatible language or for 
display files that have the USRDSPMGT keyword 
specified. 


For an application running in an OS/400 display 
data management environment that contains the 
USRDSPMGT keyword and the INVITE keyword 
in the display file, the following will occur: 


e Ifa file is active with a read outstanding when 
a record is written from another display file, a 
save of the currently displayed screen takes 
place before the write of the new record. 


e The suspended file is restored when a write is 
done to the suspended file. 


On a System/36, the save is not done for this 
situation. 


To circumvent the save command in the OS/400 
display data management environment, do the fol- 
lowing: 


1. Define a record named RECORDD in the file 
FILE1 as shown in Figure G-1. 


2. Write record RECORDD to program PGM1 
before writing record RECORDA 


By writing record RECORDD, the read outstanding 
for record RECORDB is canceled, and the 
save/restore of the record RECORDB is not 
required because there is no longer an out- 
standing invite. 


PGM1 (RPG PROGRAM) 
MOVE *ON *IN24 


WRITERECORDB 
WRITERECORDD 
WRITERECORDA 
EXFMTRECORDC 
ENDSR 
FIO IO ICICI IIR ICI TOR ICICI FOR I AK 
FILE1 
USRDSPMGT 
R RECORDB OVERLAY 
CF(01) 
INVITE 
1 18'TESTB' 
R RECORDC OVERLAY 
1 18'TESTC' 
R RECORDD OVERLAY 
FRO ICRI IORI ICICI TOR ICI FOR IA OK 
FILE2 
USRDS PMGT 
R RECORDA OVERLAY 
22 5'TEST A' 
24 DSPATR(ND) 


Figure G-1. Circumventing the Save Command 


Retain Command and Function 
Keys 


On System/36, when a program issues a write 
operation to display a record, the application can 
indicate that the command and function keys cur- 
rently active for the display station should be the 
command and function keys that are used for the 
new record. For example, if an application writes 
record REC1 (where REC1 enables command 
keys 1 through 12 and all of the function keys), 
and then the application writes record REC2 
(where REC2 keeps the command and function 
keys from REC1), then command keys 1 through 
12 and all of the function keys are enabled when 
REC2 is displayed. System/36 applications indi- 
cate that the command keys should be kept by 
specifying an R for the enable command keys 
option in the SFGR source (column 28 of the 
SFGR S specification). System/36 applications 
indicate that the function keys should be kept by 
specifying an R for the enable function keys option 
in the SFGR source (column 27 of the SFGR S 
specification). 
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AS/400 application programs can specify either a 
list of command and function keys that are valid 
when a record is displayed or an indication that 
the command and function keys that are currently 
active should remain active when a record is dis- 
played. 


OS/400 display data management allows an appli- 
cation to keep the current command keys for a 
record if the RETCMDKEY keyword is specified 
for the record. The RETCMDKEY keyword is 
automatically generated by the System/36 environ- 
ment if R is specified for command keys in the 
SFGR S specification. 


Also, OS/400 display data management allows an 
application to keep the current function keys for a 
record if the RETKEY keyword is specified for the 
record. The RETKEY keyword is automatically 
generated by the System/36 environment if R is 
specified for function keys in the SFGR S specifi- 
cation. 


System/36 Functions Not 
Supported 


This section describes the System/36 work station 
data management functions that are not supported 
by OS/400 display data management. 


If one program issues a write operation that invites 
the display and another program issues a write 
operation with the put-override function enabled 
for the same display, all the write and read oper- 
ations must use record formats from the same 
display file. For example, if program A sets up a 
read-under-format (RUF) request by writing record 
REC1 from file FILE1, the second program must 
also use FILE1 for any write operations with the 
put-override function enabled. If a different 
display file is used, all the input fields from REC1 
are changed to output-only fields when the put- 
override function is handled by OS/400 display 
data management. 


The put-override function can be used only across 
different jobs (for example, a single-requester- 
terminal (SRT) program that gives control to a 
multiple-requester-terminal (MRT) program) when 
the application programs are using RUF. If RUF 
is not in progress and the second job issues a 
write operation with the put-override function 
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enabled, all the input fields on the display are 
changed to output-only fields when the put- 
override function is handled by OS/400 display 
data management. 


On System/36, application help can return the 
data from input fields on an application help 
display. This is not supported by OS/400 display 
data management. 


Restricted DDS 
Keywords/Functions 


If the USRDSPMGT keyword is specified in the 
DDS source, the following DDS functions cannot 
be used: 


¢ DDS keywords that control clearing the 
display: 


— ASSUME 

— ERASE 

— KEEP 

— PUTRETAIN 


e ERRSFL DDS keyword 
¢ HLPCMDKEY DDS keyword 
¢ Subfile DDS keywords: 


— SFL 
— SFLCTL 


Because System/36-compatible languages do 
not support subfiles, subfiles cannot be used 
in a display file if USRDSPMGT is specified. 


e Response indicators 


Because System/36-compatible languages do 
not return indicators from the read operation 
to a display file, response indicators should 
not be specified if USRDSPMGT is used. 


e IGC conversion 


Because only one input-capable format is 
maintained on the screen at on time, IGC con- 
version is not supported on the System/36 or 
on the AS/400 in the System/36 environment. 
The IGCCNV keyword is not allowed any- 
where in the file definition when you use the 
USRDSPMGT keyword. 


¢ DDS keywords: 


—~ CHECK(M10F) 
— CHECK(M11F) 


Because specifying the DDS keywords CHECK(M10F) and CHECK(M11F) without 
CHECK(M10) and CHECK(M11) with USRDSPMGT. 
USRDSPMGT provide the same function as 
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plays. 
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This guide provides the application programmer or 
programmer with information about using the Appli- 
cation Development Tools source entry utility (SEU) 
to create and edit source members. This manual 
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editor. 
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cations that use OfficeVision functions. 
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can be used as online help information. 
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e ICF Programming, SC41-5442 
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tions and the OS/400 intersystem communications 
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keywords, system-supplied formats, return codes, 
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systems. 


IBM 5250 Information Display System Functions 
Reference Manual, SA21-9247. 
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This reference manual provides information about 
using the functions of the 5250 Information Display. 


Use this manual to use the 5250 Display Data 
Stream. 


IBM 5494 Remote Control Unit Functions Reference 
Manual, SC30-3533. 


This reference manual describes how the IBM 5494 
Remote Control Unit uses Systems Network Archi- 
tecture (SNA), Synchronous Data Link Control 
(SDLC), X.25, X.21, or Token-Ring protocols to 
communicate with the AS/400 system. In addition, 
this book describes how the 5494 manages the 
attached work stations and converts network data 
streams into protocols for 5250 work stations and 
printers. 


Program Enablers 
e DDS Reference, SC41-5712. 


This reference provides detailed descriptions of the 
entries and keywords needed to describe database 
files (both logical and physical) and certain device 
files (for displays, printers, and ICF) external to the 
user's programs. 


Use this reference to get detailed information about 
specific DDS keywords used in display files. 


CL Programming, SC41-5721. 


This guide provides a wide-ranging discussion of 
AS/400 programming topics, including control lan- 
guage (CL) programming, controlling flow and com- 
municating between programs, working with objects 
in CL programs, and creating CL programs. Other 
topics include predefined and impromptu messages 
and message handling, defining and creating user- 
defined commands and menus, and application 
testing, including debug mode, breakpoints, traces, 
and display functions. 


Use this guide to understand how to use CL for cre- 
ating application programs. 


CL Reference, SC41-5722. 


This guide provides a description of the AS/400 
control language (CL) and its OS/400 commands. 
(Non-OS/400 commands are described in the 
respective licensed program publications.) It also 
provides an overview of al/ the CL commands for 
the AS/400 system, and it describes the syntax 
rules needed to code them. 


Data Management, SC41-5710. 


This guide provides information about using files in 
application programs. This guide includes informa- 
tion on fundamental structure and concepts of data 
management support on the system. It also 
includes information on overrides and file redirection 
(temporarily making changes to files when an appli- 
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cation program is run), copying files by using 
system commands to copy data from one place to 
another, and tailoring a system using double-byte 
data. 


Use this guide for general information about using 
files in application programs. 


Printer Device Programming, SC41-5713. 


This guide provides information on how to control 
and understand printing, including printer 
connectivity, PC attached printers, and advanced 
function printing (AFP*) printers. 


Use this guide to understand printer device files. 


Tape and Diskette Device Programming, 
SC41-5716. 


This guide provides information about data manage- 
ment support for tapes and diskette. 


Use this guide to understand tape and diskette 
device files. 


System/36 Concepts and Programmer's Guide, 
$C21-9019. 


This guide tells the application programmer how the 
System/36 works, how to design and develop care- 
fully planned applications that make best use of 
system resources and features, and how to design 
and develop application components. 


Using this guide, a programmer can begin to under- 
stand what the system components are, how the 
system works, and how to design and develop 
application components. Actual coding will require 
the use of other manuals in the System/36 library. 


System/36 Creating Displays: Screen Design Aid 
and System Support Program, SC21-7902. 


This guide describes how to use the Screen Design 
Aid (SDA) or the System Support Program (SSP) to 
create and maintain menus and display formats. 

This manual also describes how to do the following: 


— Use SDA to create RPG II WORKSTN file spec- 
ifications and WSU programs. 


— Create and maintain source and procedure 
members using Source Edit Utility (SEU) 
through SDA. 


— View, print, and compile display formats. 
System/36 Environment Programming, SC41-4730. 


This guide provides information identifying the differ- 
ences in the applications process in the System/36 
environment on the AS/400 system. It helps the 
user understand the functional and operational dif- 
ferences (from a System/36 perspective) when pro- 
cessing in the System/36 environment on the 
AS/400 system. This includes an environment func- 
tional overview, considerations for migration, pro- 


gramming, communications, security, and Program Interfaces 
coexistence. 
¢ System API Reference, SC41-5801 


This reference provides information about using 
application programming interfaces (APIs) from 
high-level language programs to list data or retrieve 
descriptions and information more rapidly than using 
other interfaces. 


Use this guide to find out more information about 
the APIs. 
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BASETYPE 
summary table A-18 


display file attributes in HLL 7-1 
display file names and attributes in HLL 7-3 
display file names in HLL 7-3 
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BASETYPE (continued) 
values A-14 
basic character D-4 
BASIC statement 
I/O requests for subfiles 4-15 
beginning attribute character 
definition 2-8 
benefits 
programmable mouse button 6-70 
bibliography H-1 
bidirectional considerations 
formatting A-80 
binary return codes for program menus 9-10 
binary value 
display form A-24, A-25 
formatting A-24 
blank 
how to convert alphanumeric to DBCS D-25 
blank lines for separating 17-36 
border of window 5-7 
BOTINST (bottom instruction) tag 
overview A-10 
bottom instruction (BOTINST) tag 
overview A-10 
built-in function 
CHKOBu (check object) A-28, A-79 
CHKUSRCLS (check user class) A-28, A-80 
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CALL (Call Program) dialog command B-4 
call program 
commonly asked questions 17-37 
Call Program (CALL) dialog command B-4 
CANCEL dialog command B-6 
cancel key 
defining 6-23 
definition 6-23 
menu panel 9-2 
cancel read operation, CL command for 3-49 
cancel-invite operation 
CL command for 3-49 
ILE C function for 3-49 
ILE COBOL statement for 3-49 
ILE RPG operation for 3-49 
System/36 application compatibility G-8 
when to use 3-41 
CAnn (command attention) key 
defining 2-12 
returning to program from online help 
information 18-20 
system performance considerations 14-3 
validity considerations 3-45 
CAnn (Command Attention) keyword 
for keyboard control 2-11 


CFnn (command function) key 
CHCACCEL keyword 6-21 
defining 2-12 
returning to program from online help 
information 18-20 
system performance considerations 14-3 
validity considerations 3-45 
CFnn (Command Function) keyword 2-11, 2-12 
CGU (character generator utility) 
DBCS sort table 
copying from data file D-13 
copying to data file D-12 
Japanese DBCS master sort table 
copying from data file D-13 
copying to data file D-12 
CHANGE (Change) keyword 3-36 
Change Command Default (CHGCMDDFT) 
command 9-16 


Change Device Description (Display) (CHGDEVDSP) 


command 2-26 
Change Display File (CHGDSPF) command 
Change Display File (CHGDSPF) 
changing file description 2-2 
changing 
display files 2-5 
file description 2-2 
DFRWRT (defer write) parameter 
creating display file 3-26 
described 14-1 
ENHDSP (enhance display) parameter 6-4 
indicating DBCS files D-5 
running 2-5 
SHARE parameter 14-2 
Change Job (CHGJOB) command _ 8-7 
Change Library List (CHGLIBL) command D-8 
Change Menu (CHGMNU) command 9-16 
Change Printer File (CHGPRTF) command D-5 


Change View (CHGVIEW) dialog command B-6 


changing 
DBCS conversion dictionaries 
See editing DBCS conversion dictionaries 
display file 2-5 
file description 2-2 
file descriptions 2-5 
window 5-10 
character 
basic D-4 
double-byte 
size D-4 
system processing of D-4 
extended D-4 
selection A-9, A-155 
sentence-ending A-2 
shift-control 
See shift-control characters 
symmetric 
Arabic A-23 
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character (continued) 
symmetric (continued) 
Hebrew A-23 
character beginning attribute 2-8 
character ending attribute 2-8 
character field attribute 2-8 
character generator utility (CGU) 
DBCS sort table 
copying from data file D-13 
copying to data file D-12 
Japanese DBCS master sort table 
copying from data file D-13 
copying to data file D-12 
Character Identifier (CHRID) keyword 
description 13-1 
example 13-1 
character set and code page 
considerations when printing 17-5 
conversion, DDS 13-1 
conversion, UIM A-19 
character translation 
using 13-2 
character value 
display form A-25 
CHECK (Check) keyword 
parameters for cursor movement 2-16 
RL and RLTB parameters 2-16 
CHECK (validity checking) tag 
example, validity checking A-12 
overview A-11 
check box 
definition 6-1 
example 6-1 
CHECK(FE) (Field Exit) keyword 6-18 
CHGCMDDFT (Change Command Default) 
command 9-16 
CHGDEVDSP (Change Device Description (Display)) 
command 2-26 
CHGDSPF (Change Display File) command 
changing 
display files 2-5 
file description 2-2 
DFRWRT (defer write) parameter 
described 3-26 
when creating display file 3-26 
DFRWRT parameter 14-1 
ENHDSP (enhance display) parameter 6-4 
indicating DBCS files D-5 
running 2-5 
SHARE parameter 14-2 
CHGJOB (Change Job) command 8-7 
CHGLIBL (Change Library List) command D-8 
CHGMNU (Change Menu) command 9-16 
CHGPRTF (Change Printer File) command D-5 
CHGVIEW (Change View) dialog command B-6 
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CHKOBJ (Check Object) function A-28, A-79 
CHKUSRCLS (Check User Class) function A-28, 
A-80 
choice entry field, Common User Access 21-53 
choice-level help 6-56 
CHRID (Character Identifier) keyword 
description 13-1 
example 13-1 
CHRID (Character Identifier) parameter 
specifying 13-3 
values, table of 13-5 
CIT (title citation) tag 
example, title citations A-13 
overview A-13 
use in help module 20-4 
CL (control language) program 
examples 
program menu 9-12 
RTNPNT(*NO) for program menu 9-14 
I/O operations using 3-49 
inviting input from 3-30 
reading-from-invited-devices from 3-33 
CLASS (class definition) tag 
BASETYPE summary table A-18 
decision tree for orientation A-21 
display forms 
character value A-25 
date value A-25 
numeric values A-24 
time value A-25 
example 
class definitions A-24 
numeric values table A-24 
overview A-14 
tags allowed table A-14 
class definition (CLASS) tag 
BASETYPE summary table A-18 
decision tree for orientation A-21 
display forms 
character value A-25 
date value A-25 
numeric values A-24 
time value A-25 
example 
class definitions A-24 
example numeric values table A-24 
overview A-14 
tags allowed table A-14 
CLEAR (Clear) keyword 2-11 
Clear Lines (CLRL) keyword 
example 
differences between OVERLAY and 3-15 
with (“NO) value 3-14 
S/36 environment considerations G-1 
system performance considerations 14-2 
when to use 3-13 


clearing 
environment considerations G-1 
lines on display 
S/36 environment considerations G-1 
using the CLRL keyword 3-13 
close operation 
CL command for 3-49 
definition 3-49 
files shared in job 3-52 
ILE C function for 3-49 
ILE COBOL statement for 3-49 
ILE RPG operation for 3-49 
CLRL (Clear Lines) keyword 
example 
differences between OVERLAY and 3-15 
with (“NO) value 3-14 
S/36 environment considerations G-1 
system performance considerations 14-2 
use 3-13 
CMD (System Command) dialog command B-7 
CMDLINE (Command Line) dialog command B-7 
CMDLINE (command line) tag 
overview A-26 
code page 
alternative display 13-1 
conversion, UIM A-19 
page 420 A-20 
page 424 A-20 
part of CHRID keyword for display files 13-1 
code page and character set considerations when 
printing 17-5 
codes, major/minor return 
See major/minor return code 
colon (:) symbol A-5 
COLOR (Color) keyword 2-22 
color attribute 6-39 
color, adding to displays 2-22 
column data 
formatting A-99 
column heading 
list display 21-24 
command attention (CAnn) key 
defining 2-12 
returning to program from online help 
information 18-20 
system performance considerations 14-3 
validity considerations 3-45 
Command Attention (CAnn) keyword 
for keyboard control 2-11 
command function (CFnn) key 
defining 2-12 
returning to program from online help 
information 18-20 
system performance considerations 14-3 
validity considerations 3-45 


Command Function (CFnn) keyword 2-12 
command key 
See command attention (CAnn) key 
See command function (CFnn) key 
command line 
entered too long 17-20 
interpretation 17-19 
optional 21-34 
pop-up window 17-32 
restrictions 17-19 
tools 21-37 
window 17-32 
window example 17-32 
Command Line (CMDLINE) dialog command B-7 
command line (CMDLINE) tag 
overview A-26 
command prompting B-13 
command, CL 
Add Message Description (ADDMSGD) 9-9 
Add Search Index Entry (ADDSCHIDXE) 20-17 
ADDMSGD (Add Message Description) 9-9 
ADDSCHIDXE (Add Search Index Entry) 20-17 
ALCOB4 (Allocate Object) 3-1 
Allocate Object (ALCOBJ) 3-1 
canceling read operation with 3-49 
Change Command Default (CHGCMDDFT) 9-16 
Change Device Description (CHGDEVDSP) 2-26 
Change Display File (CHGDSPF) 
changing file description 2-5 
indicating DBCS files D-5 
running 2-5 
SHARE parameter 14-2 
Change Job (CHGJOB) 8-7 
Change Library List (CHGLIBL) D-8 
Change Menu (CHGMNU) 9-16 
Change Printer File (CHGPRTF) D-5 
CHGCMDDFT (Change Command Default) 9-16 
CHGDEVDSP (Change Device Description) 2-26 
CHGDSPF (Change Display File) 
changing file description 2-5 
DFRWRT parameter 14-1 
indicating DBCS files D-5 
SHARE parameter 14-2 
CHGJOB (Change Job) 8-7 
CHGLIBL (Change Library List) D-8 
CHGMNU (Change Menu) 9-16 
CHGPRTF (Change Printer File) D-5 
Copy DBCS Font Table (CPYIGCTBL) D-9 
Copy DBCS Sort Table (CPYIGCSRT) 
copying DBCS master sort table from data 
file D-13 
copying DBCS master sort table to data 
file D-12 
CPYIGCSRT (Copy DBCS Sort Table) 
copying DBCS master sort table from data 
file D-13 
copying DBCS master sort table to data 
file D-12 
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command, CL (continued) 
CPYIGCTBL (Copy DBCS Font Table) D-9 
Create Command (CRTCMD) 20-16 


Create Control Language Program (CRTCLPGM) 


program menus 9-12 
Create DBCS Conversion Dictionary 
(CRTIGCDCT) D-15 
Create Display File (CRTDSPF) 
building display with 1-4 
creating display files 2-4 
DFRWRT parameter 14-1 
display file menus 9-9 
indicating DBCS files D-5 
program menus 9-12 
SHARE parameter 14-2 
Create Document (CRTDOC) 20-18 
Create Duplicate Object (CRTDUPOBJ) 
DBCS conversion dictionary D-15 
use 9-16 
Create Edit Description (CRTEDTD) 2-23 
Create Menu (CRTMNU) 
display file menus 9-9 
program menus 9-13 
Create Message File (CRTMSGF) 9-9 
Create Panel Group (CRTPNLGRP) 
building display with 1-5 
use 20-15 
Create Printer File (CRTPRTF) D-5 
Create Search Index (CRTSCHIDX) 20-16 
Create Table (CRTTBL) 13-4 
creating your own 20-16 


CRTCLPGM (Create Control Language Program) 


program menus 9-12 
CRTCMD (Create Command) 20-16 
CRTDOC (Create Document) 20-18 
CRTDSPF (Create Display File) 

building display with 1-4 

creating display files 2-4 

DFRWRT (defer write) parameter 14-1 

display file menus 9-9 

indicating DBCS files D-5 

program menus 9-12 

SHARE parameter 14-2 
CRTDUPOB4 (Create Duplicate Object) 


saving and restoring DBCS dictionaries D-15 


use 9-16 
CRTEDTD (Create Edit Description) 2-23 
CRTIGCDCT (Create DBCS Conversion 
Dictionary) D-15 
CRTMNU (Create Menu) 
display file menus 9-9 
program menus 9-13 
CRTMSGF (Create Message File) 9-9 
CRTPNLGRP (Create Panel Group) 
building display with 1-5 
use 20-15 
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command, CL (continued) 

CRTPRTF (Create Printer File) D-5 

CRTSCHIDX (Create Search Index) 20-16 

CRTTBL (Create Table) 13-4 

Delete DBCS Conversion Dictionary 
(DLTIGCDCT) D-19 

Delete DBCS Font Table (DLTIGCTBL) D-10 

Delete DBCS Sort Table (DLTIGCSRT) D-14 

Delete Menu (DLTMNU) 9-17 

Delete Override (DLTOVR) 7-5 

Delete Panel Group (DLTPNLGRP) 20-15 

Delete Search Index (DLTSCHIDXE) 20-17 

Display DBCS Conversion Dictionary 
(DSPIGCDCT) D-19 

Display Edit Description (DSPEDTD) 2-24 

Display File Description (DSPFD) 2-7 

Display File Field Description (DSPFFD) 2-7 

Display Help Document (DSPHLPDOC) 20-19 

Display Menu Attributes (DSPMNUA) 9-16 

Display Override (DSPOVR) 7-6 


Display Program References (DSPPGMREF) 2-7 


DLTIGCDCT (Delete DBCS Conversion 
Dictionary) D-19 

DLTIGCSRT (Delete DBCS Sort Table) D-14 

DLTIGCTBL (Delete DBCS Font Table) D-10 

DLTMNU (Delete Menu) 9-17 

DLTOVR (Delete Override) 7-5 

DLTPNLGRP (Delete Panel Group) 20-15 


DLTSCHIDXE (Delete Search Index Entry) 20-17 


DSPEDTD (Display Edit Description) 2-24 
DSPFD (Display File Description) 2-7 
DSPFFD (Display File Field Description) 2-7 
DSPHLPDOC (Display Help Document) 20-19 
DSPIGCDCT (Display DBCS Conversion 
Dictionary) D-19 
DSPMNUA (Display Menu Attributes) 9-16 
DSPOVR (Display Override) 7-6 


DSPPGMREF (Display Program References) 2-7 


Edit DBCS Conversion Dictionary 
(EDTIGCDCT) D-16 
EDTIGCDCT (Edit DBCS Conversion 
Dictionary) D-16 
End Receive (ENDRCV) 3-31 
ENDRCV (End Receive) 3-31 
GO (Go to Menu) 
generic menu specification 9-16 
use 9-1 
Go to Menu (GO) 
generic menu specification 9-16 
use 9-1 
help for, assigning 20-16 
Initialize Diskette (INZDKT) D-9 
INZDKT (Initialize Diskette) D-9 
Move Object (MOVOBJ) D-15 
MOVOB4J (Move Object) D-15 
OVERLAY (Overlay) keyword 
effect on help-list updating 18-16 


command, CL (continued) 


Override with Display File (OVRDSPF) 
compared to CHGDSPF 2-2 
file attributes 7-1 
filenames 7-3 
file names and attributes 7-3 
indicating DBCS files D-5 
Override with Printer File (OVRPRTF) D-5 
overrides 
commands that restrict 7-9 
improving performance for 14-2 
OVRDSPF (Override with Display File) 
compared to CHGDSPF 2-2 
file attributes 7-1 
filenames 7-3 
file names and attributes 7-3 
indicating DBCS files D-5 
OVRPRTF (Override with Printer File) D-5 
Remove Search Index Entry (RMVSCHIDXE) 20-17 
Rename Object (RNMOBJ) D-15 
Restore Library (RSTLIB) D-15 
Restore Object (RSTOBuJ) 
DBCS conversion dictionary D-15 
DBCS sort table D-12 
RMVSCHIDXE (Remove Search Index Entry) 20-17 
RNMOBJ (Rename Object) D-15 
RSTLIB (Restore Library) D-15 
RSTOB4J (Restore Object) 
DBCS conversion dictionary D-15 
DBCS sort table D-12 
RVKOBJAUT (Revoke Object Authority) D-15 
SAVCHGOBJ (Save Changed Object) D-15 
Save Changed Object (SAVCHGOBJ) D-15 
Save Library (SAVLIB) D-15 
Save Object (SAVOBJ) 
DBCS conversion dictionaries D-15 
DBCS sort table D-12 
Save System (SAVSYS) 
DBCS conversion dictionary D-15 
saving DBCS sort tables D-12 
SAVLIB (Save Library) D-15 
SAVOBJ (Save Object) 
DBCS conversion dictionaries D-15 
DBCS sort table D-12 
SAVSYS (Save System) 
DBCS conversion dictionaries D-15 
saving DBCS sort tables D-12 
Start Character Generator Utility (STRCGU) D-10 
Start Programming Development Manager 
(STRPDM) 1-1 
Start Search Index (STRSCHIDX) 20-8 
Start Source Entry Utility (STRSEU) 2-7 
STRCGU (Start Character Generator Utility) D-10 
STRPDM (Start Programming Development 
Manager) 1-1 
STRSCHIDX (Start Search Index) 20-8 


command, CL (continued) 
STRSEU (Start Source Entry Utility) 2-7 
Vary Configuration (VRYCFG) D-10 
VRYCFG (Vary Configuration) D-10 
commands that are too long 17-20 
comment A-6 
common feedback area 
definition 3-3 
common key assignments 21-38 
Common User Access (CUA) 
choice entry field 21-53 
description 21-50 
entry dialog actions, table of 21-51 
entry display 21-53 
entry fields 21-54 
function key area 21-52 
information displays 21-55 
list display, example 21-55 
menu display, single-choice 21-52 
message line relationship 21-52 
relationship to AS/400 system 21-1 
selection choices 21-53 
single selection field operation, guidelines 21-53 
compact definition list 
example A-58 
concatenation symbol A-5 
COND (condition definition) tag 
CHKOBJ (Check Object) built-in function A-28 
CHKUSRCLS (Check User Class) built-in 
function A-28 
example, conditioning option A-29 
overview A-27 
condition definition (COND) tag 
CHKOBJ (Check Object) built-in function A-28 
CHKUSRCLS (Check User Class) built-in 
function A-28 
example, conditioning option A-29 
overview A-27 
condition name, screen size 2-24 
conditional expression A-27, A-79 
conditional operator A-27 
conditioning 
option 
example A-29 
confirmation list panel, creating 16-27 
confirmation panel source 16-28 
confirmation processing 
application programming 16-31 
automatically 16-31 
constant field 
definition 2-10 
inserting text from message description 2-16 
using 2-10 
content separator A-1 
contextual help 
defining in UIM 17-16 
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contextual help (continued) 
defining on display 18-3 
definition 19-2 
continued attribute 
example A-1 
continued-entry field 
backward field-exit processing 6-49 
creating 6-42 
DBCS considerations 6-43 
example 6-43 
forward field-exit processing 6-49 
keyboard function 6-44 
word wrap 6-43 
control character, shift 
description of D-3 
inserting D-6 
control language (CL) program 
examples 
program menu 9-12 
RTNPNT(*NO) for program menu 9-14 
I/O operations using 3-49 
inviting input from 3-30 
reading-from-invited-devices from 3-33 
control value 6-36 
controller, display station G-2 
controlling 
availability of choices 6-36 
list entries on list display 17-10 
convention 
recommended 
list action (LISTACT) tag A-94 
pull-down field choice (PDFLDC) tag A-136 
required 
list action (LISTACT) tag A-94 
pull-down field choice (PDFLDC) tag A-136 
conversion 
alphabetic A-4 
character set and code page, DDS_ 13-1 
character set and code page, UIM A-19 
conversion, DBCS 
alphanumeric applications to DBCS 
applications D-8 
alphanumeric blanks to DBCS blanks D-25 
changing DBCS conversion dictionaries used D-20 
deleting unwanted DBCS words D-25 
description D-19 
entering double-byte data D-21 
function D-20 
many alphanumeric entries at one time D-24 
one alphanumeric entry to double-byte entry D-22 
performing (including example operations) D-21 
use while editing DBCS conversion dictionary D-25 
where you can use D-20 
Copy DBCS Font Table (CPYIGCTBL) command 
copying from tape or diskette D-9 
copying onto tape or diskette D-9 
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Copy DBCS Sort Table (CPYIGCSRT) command 
copying DBCS master sort table from data file D-13 
copying DBCS master sort table to data file D-12 
copying 
DBCS files 
from tape or diskette D-9 
onto tape or diskette D-9 

DBCS font table 
copying from tape or diskette (restoring) D-9 
copying onto diskette (saving) D-9 

DBCS sort table 
copying from file (move from System/36) D-13 
copying to file (move to System/36 or 

AS/Entry) D-12 

COPYR (copyright) tag 
overview A-30 

copyright (COPYR) tag 
overview A-30 

country-designated selection character 17-13 

CPA8424 inquiry message D-10 

CPF4001-40FF message 8-10 

CPF4101-43FF message 8-10 

CPF4401-44FF message 8-10 

CPF4501-46FF message 8-10 

CPF4701-48FF message 8-10 

CPF4901-49FF message 8-10 

CPF5001-50FF message 8-10 

CPF5101-53FF message 8-10 

CPF5501-56FF message 8-10 

CPYIGCSRT (Copy DBCS Sort Table) command 
copying DBCS master sort table from data file D-13 
copying DBCS master sort table to data file D-12 

CPYIGCTBL (Copy DBCS Font Table) command 
copying from tape or diskette D-9 
copying onto tape or diskette D-9 

Create Command (CRTCMD) command 20-16 

Create Control Language Program (CRTCLPGM) 

command 9-12 
Create DBCS Conversion Dictionary (CRTIGCDCT) 
command D-15 

Create Display File (CRTDSPF) command 
building display with 1-4 
creating display files 2-4 
DFRWRT (defer write) parameter 

improving performance with 14-1 
write operation 3-26 
display file menus 9-9 
ENHDSP (enhance display) parameter 6-4 
indicating DBCS files D-5 
program menus 9-12 
SHARE parameter 14-2 

Create Document (CRTDOC) command 20-18 

Create Duplicate Object (CRTDUPOBJ) command 
DBCS conversion dictionaries D-15 
use 9-16 


Create Edit Description (CRTEDTD) command 
example F-5 
running 2-23 
use F-5 
Create Menu (CRTMNU) command 
display file menus 9-9 
program menus 9-13 
Create Message File (CRTMSGF) command 9-9 
Create Panel Group (CRTPNLGRP) command 
building display with 1-5 
use 20-15 
Create Printer File (CRTPRTF) command D-5 
Create Search Index (CRTSCHIDX) command 20-16 
Create Table (CRTTBL) command 13-4 
creating 
application display with online help information, steps 
for 1-1 
confirmation list panel 16-27 
continued-entry field 6-42 
creating 6-35 
data presentation panel 16-32 
DBCS conversion dictionaries D-15 
display file and description 2-4 
edit description F-5 
graphical look 6-1 
horizontal selection field 6-14 
list panel 16-13 
menu bar 6-7 
menu bar panel 16-50 
menu panel 16-6 
message 8-1 
object 16-3 
pull-down menu 6-18 
scroll bar 6-31 
selection list 6-26 
vertical multiple-choice selection field 6-14 
vertical single-choice selection field 6-13 
window 5-3 
CRTCLPGM (Create Control Language Program) 
command 9-12 
CRTCMD (Create Command) command 20-16 
CRTDOC (Create Document) command 20-18 
CRTDSPF (Create Display File) command 
building display with 1-4 
creating display files 2-4 
DFRWRT (defer write) parameter 
improving performance with 14-1 
write operation 3-26 
display file menus 9-9 
ENHDSP (enhance display) parameter 6-4 
indicating DBCS files D-5 
program menus 9-12 
SHARE parameter 14-2 
CRTDUPOBJ (Create Duplicate Object) command 
DBCS conversion dictionaries D-15 
use 9-16 


CRTEDTD (Create Edit Description) command 
example F-5 
running 2-23 
use F-5 
CRTIGCDCT (Create DBCS Conversion Dictionary) 
command D-15 
CRTMNU (Create Menu) command 
display file menus 9-9 
program menus 9-13 
CRTMSGF (Create Message File) command 9-9 
CRTPNLGRP (Create Panel Group) command 
building display with 1-5 
use 20-15 
CRTPRTF (Create Printer File) command D-5 
CRTSCHIDX (Create Search Index) command 20-16 
CRTTBL (Create Table) command 13-4 
CSRINPONLY (Cursor Input Only) keyword 2-16 
CSRLOC (Cursor Location) keyword 3-28 
CUA (Common User Access) 
choice entry field 21-53 
description 21-50 
entry dialog actions, table of 21-51 
entry display 21-53 
entry fields 21-54 
function key area 21-52 
information displays 21-55 
list display, example 21-55 
menu display, single-choice 21-52 
message line relationship 21-52 
relationship to AS/400 system 21-1 
selection choices 21-53 
single selection field operation, guidelines 21-53 
cursor 
actions 6-61 
movement 
cursor keys 6-62 
horizontal selection field 6-16 
right-to-left 2-16 
tab key 6-61 
to input-capable positions only 2-16 
vertical selection field 6-15 
position when help text displayed 17-17 
positioning 
after output operation 3-28 
during I/O operations 3-41 
each page of the subfile record 4-24 
rules for list displays 21-31 
subfiles 4-24 
System/36 application compatibility for display 
files G-4 
progression 
entry field 2-17 
restrict 
PULLDOWN keyword 6-24 
WINDOW keyword 5-5 
returning position to an application 3-29 
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cursor in window 5-5 


Cursor Input Only (CSRINPONLY) keyword 2-16 


cursor key 
movement 6-62 


D 


damaged DBCS devices D-10 
data 


ASSUME keyword considerations for passing 11-1 


checking validity of 3-37 
data 
receiving 3-4 
describing inside or outside your program 2-3 
externally described 
definition 2-3 
using 2-3 
input 
handling negative numeric 3-40 
keeping 3-36 
KEEP keyword considerations for passing 11-1 
levels of description 2-2 
passing 
between programs 11-1 


between programs in same routing step 11-1 


between routing steps 11-3 
program-described 

definition 2-3 

described 2-4 

using 2-27 
receiving 3-4 
relationship to display file 2-2 
rolling between two lines on display 3-16 
sending and receiving 3-4 

DATA (data presentation area) tag 

example 

data entry panel A-34 


data entry panel with nested data group A-36 
data presentation area with menu area A-36 


two presentation areas for data items A-35 
two-column format in data entry panel A-34 
overview A-31 
tags allowed table A-31 
data area help 19-8 
data column (DATACOL) tag 
overview A-39 
data description specifications (DDS) 
See also display file 
See also keyword, DDS 
CAnn keys, restrictions 2-13 
changing 2-5 
CHECK(FE) (Field Exit) keyword 6-18 
DBCS capabilities D-5 
DDS form 2-7 
definition 1-1 
display files 
passing data between programs 11-1 
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data description specifications (DDS) (continued) 


display files (continued) 
passing data between routing steps 11-3 
use in 2-7 
DSPRL (Display Right-to-Left) keyword 2-19 
entry displays 21-46 
ERRMSG (Error Message) keyword 5-6 
ERRMSGID (Error Message ID) keyword 5-6 
ERRSFL (Error Subfile) keyword 5-6 
example 
5250 display station problems 3-45 
CLRL and OVERLAY keywords, differences 
between 3-15 
display file menu 9-8 
display file source 2-7 
DSPATR(PC) keyword 4-24 
DSPMOD keyword 3-27 
DSPMOD keyword with subfiles 4-17 
ERRSFL keyword 8-4 
GRDATR (Grid Line Attribute) keyword 6-80 
GRDBOX (Grid Box) keyword 6-80 
GRDCLR (Grid Clear) keyword 6-80 
GRDLIN (Grid Line) keyword 6-80 
GRDRCD (Grid Record) keyword 6-80 
grid line structure 6-80 
HLPCMDKEY keyword 18-20 
HLPCMDKEY keyword with response 
indicators 18-21 
HLPDOC keyword 18-10 
HLPDOC keyword with option indicators 18-11 
HLPPNLGRP keyword 18-7 
HLPPNLGRP keyword with option 
indicators 18-8 
HLPRCD keyword 18-13 
HLPRCD keyword with option indicators 18-14 
message subfile 4-23 
mnemonic 6-38 
OVERLAY and CLRL keywords, differences 
between 3-15 
program menu 9-11 
PULLINPUT keyword 6-54 
push button 6-35 
PUTOVR keyword 3-18 
PUTOVR keyword for more efficient coding 3-20 
PUTOVR keyword for repeatedly entered 
data 3-21 
PUTRETAIN keyword, field level 3-24 
PUTRETAIN keyword, record level 3-24 
ROLLUP, SFLSIZ, and SFLPAG keywords 4-19 
scroll bar 6-33 
secondary help 18-18 
selection field 6-12 
selection list 6-26 
SFLMSGID keyword 8-5 
SFLNXTCHG keyword 4-22 


SFLPAG, SFLSIZ, and ROLLUP keywords 4-19 
SFLSIZ, ROLLUP, and SFLPAG keywords 4-19 


data description specifications (DDS) (continued) 
example (continued) 
subfiles for two display sizes 2-25 
two display sizes 2-24 
variable-length record 4-20 
field 
color (table) 2-22 
emphasizing (table) 2-21 
help record 5-7 
information displays 21-47 
keywords ignored if display modes are 
changed 3-28 
list display 21-49 
menu displays 21-45 
MSGLOC (Message Location) keyword 5-6 
NOCCSID (No CCSID) keyword 13-3 
processing order for subfile control 4-9 
program logic 4-31 
programming example 5-15 
RMVWDW (Remove Window) keyword 5-12 
SFLMSG (Subfile Message) keyword 5-6 
SFLMSGID (Subfile Message identifier) 
keyword 5-6 
subfile, describing with 4-3 
use 2-1 
USRRSTDSP (User Restore Display) keyword 5-13 
validity-checking keyword 5-6 
WDWBORDER (Window Border) keyword 5-7 
window 5-1 
WINDOW (Window) keyword 5-3 
data entry panel 
example A-34 
introduction 16-49 
nested data group example A-36 
data group (DATAGRP) tag 
overview A-40 
data item (DATAI) tag 
overview A-42 
data item choices (DATAC) tag 
overview A-38 
data item extender (DATAIX) tag 
overview A-47 
data item group scrolling 17-16 
data presentation area (DATA) tag 
example 
data entry panel A-34 
data entry panel with nested data group A-36 
data presentation area with menu area A-36 
two presentation areas for data items A-35 
two-column format in data entry panel A-34 
overview A-31 
tags allowed table A-31 
data presentation panel application 
programming 16-46 
data presentation panel creating 16-32 


data presentation panel source 16-35 
data queue 
waiting on display file and ICF file 12-1 
data selection field (DATASLT) tag 
example 
data entry panel A-53 
multiple-selection field A-53 
overview A-51 
tags allowed table A-51 
data selection field choice (DATASLTC) tag 
overview A-55 
data stream, 5250 display 
See user-defined data stream (UDDS) 
data stream, user-defined 
See user-defined data stream (UDDS) 
data tag, modified 2-10 
DATAC (data item choices) tag 
overview A-38 
DATACOL (data column) tag 
overview A-39 
DATAGRP (data group) tag 
overview A-40 
DATAI (data item) tag 
overview A-42 
DATAIX (data item extender) tag 
overview A-47 
DATASLT (data selection field) tag 
example 
data entry panel A-53 
multiple-selection field A-53 
overview A-51 
tags allowed table A-51 
DATASLTC (data selection field choice) tag 
overview A-55 
date value 
display form A-25 
DBCS (double-byte character set) printing 17-37 
DBCS and national language considerations 20-12 
DBCS applications, converted from alphanumeric 
applications D-8 
DBCS code scheme D-1 
DBCS codes, not valid D-3 
DBCS command 
See command 
DBCS conversion 
alphanumeric blanks to DBCS blanks D-25 
changing DBCS conversion dictionaries used D-20 
deleting unwanted DBCS words D-25 
description D-19 
entering double-byte data D-21 
function D-20 
many alphanumeric entries at one time D-24 
one alphanumeric entry to double-byte entry D-22 
performing (including example operations) D-21 
use while editing DBCS conversion dictionary D-25 
where you can use D-20 
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DBCS conversion dictionary 
adding the first entries to D-17 
beginning editing D-17 
creating D-15 
deleting D-19 
deleting entry D-18 
description D-14 
displaying and printing D-19 
editing (adding and changing terms) D-16 
editing suggestions D-18 
ending editing D-18 
moving entries D-18 
printing after displaying D-19 
system-supplied D-14 
user-created D-15 
DBCS device 
damaged D-10 
display stations D-6 
DBCS display stations and number of input 
fields D-6 
DBCS field 
continued-entry field 6-43 
determining the length D-4 
DBCS file 
description of D-5 
restrictions D-6 
specifying D-5 
DBCS font table 
checking for existence of D-8 
copying 
from tape (restore) D-10 
onto diskette (save) D-9 
deleting D-10 
description of D-8 
restoring from tape or diskette D-9 
saving onto diskette D-9 
system-supplied D-8 
DBCS grid line structure 
See grid line structure 
DBCS master sort table, Japanese 
copying from data file D-13 
copying to data file D-13 
DBCS sort table 
checking for existence of D-12 
copying 
from data file (move from System/36) D-13 
to data file (move to System/36 or 
AS/Entry) D-12 
deleting D-14 
description D-11 
restoring from tape or diskette D-12 
saving onto diskette D-12 
DBCS words, deleting during DBCS 
conversion D-25 


DBCS-graphic and shift control characters D-6 
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DBCS-graphic fields on double-byte displays D-7 


DDS (data description specifications) 
See also display file 
See also keyword, DDS 
CAnn keys, restrictions 2-13 
changing 2-5 
CHECK(FE) (Field Exit) keyword 6-18 
DBCS capabilities D-5 
DDS form 2-7 
definition 1-1 
display files 
passing data between programs 11-1 
passing data between routing steps 11-3 
use in 2-7 
DSPRL (Display Right-to-Left) keyword 2-19 
entry displays 21-46 
ERRMSG (Error Message) keyword 5-6 
ERRMSGID (Error Message ID) keyword 5-6 
ERRSFL (Error Subfile) keyword 5-6 
example 
5250 display station problems 3-45 
CLRL and OVERLAY keywords, differences 
between 3-15 
display file menu 9-8 
display file source 2-7 
DSPATR(PC) keyword 4-24 
DSPMOD keyword 3-27 
DSPMOD keyword with subfiles 4-17 
ERRSFL keyword 8-4 
GRDATR (Grid Line Attribute) keyword 6-80 
GRDBOX (Grid Box) keyword 6-80 
GRDCLR (Grid Clear) keyword 6-80 
GRDLIN (Grid Line) keyword 6-80 
GRDRCD (Grid Record) keyword 6-80 
grid line structure 6-80 
HLPCMDKEY keyword 18-20 
HLPCMDKEY keyword with response 
indicators 18-21 
HLPDOC keyword 18-10 


HLPDOC keyword with option indicators 18-11 


HLPPNLGRP keyword 18-7 

HLPPNLGRP keyword with option 
indicators 18-8 

HLPRCD keyword 18-13 


HLPRCD keyword with option indicators 18-14 


message subfile 4-23 

mnemonic 6-38 

OVERLAY and CLRL keywords, differences 
between 3-15 

program menu 9-11 

PULLINPUT keyword 6-54 

push button 6-35 

PUTOVR keyword 3-18 


PUTOVR keyword for more efficient coding 3-20 


PUTOVR keyword for repeatedly entered 
data 3-21 
PUTRETAIN keyword, field level 3-24 


DDS (data description specifications) (continued) 
example (continued) 
PUTRETAIN keyword, record level 3-24 
ROLLUP, SFLSIZ, and SFLPAG keywords 4-19 
scroll bar 6-33 
secondary help 18-18 
selection field 6-12 
selection list 6-26 
SFLMSGID keyword 8-5 
SFLNXTCHG keyword 4-22 
SFLPAG, SFLSIZ, and ROLLUP keywords 4-19 
SFLSIZ, ROLLUP, and SFLPAG keywords 4-19 
subfiles for two display sizes 2-25 
two display sizes 2-24 
variable-length record 4-20 
field 
color (table) 2-22 
emphasizing (table) 2-21 
help record 5-7 
information displays 21-47 
keywords ignored if display modes are 
changed 3-28 
list display 21-49 
menu displays 21-45 
MSGLOC (Message Location) keyword 5-6 
NOCCSID (No CCSID) keyword 13-3 
processing order for subfile control 4-9 
program logic 4-31 
programming example 5-15 
RMVWDW (Remove Window) keyword 5-12 
SFLMSG (Subfile Message) keyword 5-6 
SFLMSGID (Subfile Message identifier) 
keyword 5-6 
subfile, describing with 4-3 
use 2-1 
USRRSTDSP (User Restore Display) keyword 5-13 
validity-checking keyword 5-6 
WDWBORDER (Window Border) keyword 5-7 
window 5-1 
WINDOW (Window) keyword 5-3 
DDS form 2-7 
DDS keyword 
See keyword, DDS 
DDS record 
See record, DDS 
decimal point, edit description for F-4 
Default (DFT) keyword 
use 3-26 
with ASSUME keyword 11-1 
default value 
fields 3-26 
defining 
accelerator key 6-21 
application help 6-56 
application pop-up window 17-30 
application window 17-30 


defining (continued) 
attributes for entry fields 2-18 
cancel key 6-23 
choice colors and attributes 6-39 
choice-level help 6-56 
contextual help in UIM 17-16 
cursor progression for entry fields 2-17 
dialog variables 17-1 
function keys 17-20 
function keys and VARUPD value 17-21 
header area 17-36 
help for field 6-59 
lists 17-8 
menu object 16-6 
menu-bar switch key 6-22 
mnemonic 6-38 
MNUBARDSP (Menu-Bar Display) keyword 
application record 6-50, 6-62 
menu-bar record 6-51, 6-65 
panel group object 16-13 
prolog area 17-36 
scrollable areas 17-14 
definition 
panel A-2 
definition list 
device C-4 
definition list (DL) tag 
example 
compact definition list A-58 
definition list A-58 
overview A-57 
tags allowed table A-57 
use in help module 20-5 
Delete DBCS Conversion Dictionary (DLTIGCDCT) 
command D-19 
Delete DBCS Font Table (DLTIGCTBL) command 
deleting D-10 
use D-10 
Delete DBCS Sort Table (DLTIGCSRT) 
command D-14 
Delete Menu (DLTMNU) command 9-17 
Delete Override (DLTOVR) command 7-5 
Delete Panel Group (DLTPNLGRP) command 20-15 
Delete Search Index Entry (RMVSCHIDXE) 
command 20-17 
deleting 
DBCS conversion dictionary D-19 
DBCS font table D-10 
DBCS sort tables D-14 
DBCS words D-25 
menu displays 9-17 
overrides 7-5 
panel group 20-15 
search index 20-17 
window 5-12 
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description 
field-level 
definition 2-2 
use 2-2 
file-level 
definition 2-3 
use 2-3 
record-level 
definition 2-3 
use 2-3 
description, file 
changing 
reasons for 2-2 
with the CHGDSPF command 2-5 
creating for display file 2-4 
definition 1-1 
detecting changes in 2-6 
determining 2-2 
descriptive text area, entry displays 21-16 
device 
DBCS 
damaged D-10 
display stations D-6 
device definition list 
definition 3-3 
part of open feedback area C-4 
DFRWRT (defer write) parameter 
improving performance with 14-1 
restrictions 3-26 
using 3-26 
DFT (Default) keyword 
use 3-26 
with ASSUME keyword 11-1 
DFTVAL (Default Value) keyword 3-26 
dialog command 
ACTIONS (Menu Bar Cursor Action) B-4 
CALL (Call Program) B-4 
Call Program (CALL) B-4 
CANCEL (Cancel) B-6 
Change View (Change View) B-6 
CHGVIEW (Change View) B-6 
CMD (System Command) B-7 
CMDLINE (Command Line) B-7 
Command Line (CMDLINE) B-7 
Display Help (DSPHELP) B-7 
Display Home Menu (HOME) B-9 
Display Message (MSG) _ B-11 
Display More Function Keys (MOREKEYS) 
DSPHELP (Display Help) B-7 
effects of B-1 
ENTER (Enter) B-8 
entry field prompting B-13 
EXIT (Exit Display) B-8 
Exit Display (EXIT) B-8 
Extended Help (EXTHELP) B-9 
EXTHELP (Extended Help) B-9 
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dialog command (continued) 


HELP (Help) B-9 

HELPHELP (Help Help) B-9 

HELPIDX (Help Index) B-9 

HOME (Display Home Menu) B-9 

introduction B-1 

KEYSHELP (Keys Help) B-10 

MENU (Menu) B-10 

Menu Bar Cursor Action (ACTIONS) B-4 
MOREKEYS (Display More Function Keys) B-10 
Move to Top (MOVETOP) B-11 

MOVETOP (Move to Top) B-11 

MSG (Display Message) B-11 

PAGEDOWN (Page Down) B-11 

PAGEUP (Page Up) B-12 

PRINT (Print Display) B-12 

Print Display (PRINT) B-12 

PROMPT (Prompt) B-13 

prompting an entry field B-13 

PULLDOWN (Display Pull-down Menu) B-14 
RETRIEVE (Retrieve Command String) B-14 
Retrieve Command String (RETRIEVE) B-14 
RETURN (Return Control to Application) B-14 
Return Control to Application (RETURN) B-14 
System Command (CMD) B-7 

valid uses B-1 

variable update (VARUPD) attribute B-4 
VARUPD attribute B-4 


dialog variable 


defined by UIM A-167 
defining 17-1 
definition 17-1 
displaying panel field value using 17-4 
error messages 17-3 
incorrect display characters 17-4 
initial value 17-2 
restrictions 17-3 
variable pool 17-2 
Z36ENV A-167 
ZCANCEL A-167 
ZDBCS_ A-167 
ZDSPSIZ A-167 
ZEXIT A-167 

ZJOB A-167 
ZJOBNBR_  A-167 
ZLMTCPB_ A-167 
ZMENU_ A-167 
ZMNULIB_ A-167 
ZSYSNAM_ A-167 
ZUSER A-167 


dictionary, DBCS conversion 


adding the first entries to D-17 
beginning editing D-17 
creating D-15 

deleting D-19 

deleting entry D-18 


dictionary, DBCS conversion (continued) 
description D-14 
displaying and printing D-19 
editing (adding and changing terms) D-16 
editing suggestions D-18 
ending editing D-18 
moving entries D-18 
printing after displaying D-19 
system-supplied D-14 
user-created D-15 
differences between pull-down menus and pop-up 
windows 17-28 
diskette file 
DBCS D-5 
display 
creating UIM 16-13 
list 17-8 
panel field value using dialog variables 17-4 
UIM 16-13 
user interface manager 16-13 
display attribute 
choices 6-39 
color fields 2-22 
emphasizing fields 2-21 
display attribute (‘DSPATR) parameter 6-40 
Display Attribute (DSPATR) keyword 
example source for PC value 4-24 
use 3-28 
with ASSUME keyword 11-1 
with program-to-system field 2-21 
display character 
incorrect 17-4 
Display DBCS Conversion Dictionary (DSPIGCDCT) 
command D-19 
display device file 
See display file 
display device support, DBCS D-6 
Display Edit Description (DSPEDTD) 
command 2-24 
display file 
See also data description specifications (DDS) 
See also subfile 
See also window 
ASSUME (Assume) 
considerations 11-1 
attributes for fields, System/36 application compat- 
ibility G-3 
cancel-invite operation, System/36 application com- 
patibility G-8 
characteristics of 2-1 
closing 3-49 
command key validity 3-45 
creating 
ways for 2-5 
with DDS 2-4 
without DDS 2-27 


display file (continued) 
cursor positioning, System/36 application compat- 
ibility G-4 
DBCS D-5 
defining input and output 2-28 
defining your display in 2-1 


definition 1-1 
description 
creating 2-4 


how changes are applied to 2-6 
display station controller, System/36 application com- 
patibility G-2 
displaying messages, System/36 application compat- 
ibility G-4 
edit codes, user-defined F-4 
edit descriptions F-1 
erase-input-fields function, System/36 application 
compatibility G-3 
establishing 2-1 
example, programming 5-15 
examples 
assigning space to program-described 2-27 
building with online help 1-1 
DDS source 2-7 
replacing record formats on display 3-8 
file entry field attributes 12-1 
function keys, System/36 application 
compatibility G-7 
HELP and HLPRTN keywords, System/36 application 
compatibility G-7 
input data 
System/36 application compatibility G-2 
input data, System/36 application compatibility G-2 
input-only, defining 2-28 
lock 3-1 
maximum number of record formats in 2-15 
obtaining information about 3-3 
online help information 
See online help information 
opening 3-2 
operations supported by the system and high-level 
languages 
CL commands 3-49 
ILE C functions 3-49 
ILE COBOL statements 3-49 
ILE RPG operations 3-49 
operator changes, System/36 application compat- 
ibility G-3 
output-only, defining 2-28 
overriding 
attributes in HLL programs 7-1 
file names and attributes in HLL programs 7-3 
file names in HLL programs 7-3 
passing data 
between programs 11-1 
between routing steps 11-3 
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display file (continued) 
put with explicit override, System/36 
compatibility G-6 
relationship to data 2-2 
retain command and function keys, System/36 appli- 
cation compatibility G-9 
return codes. E-1 
screen size, specifying to improve 
performance 14-1 
self-check, System/36 application compatibility G-2 
sharing in same job 3-50 
signed numeric data, System/36 application compat- 
ibility G-7 
suspended 3-43 
System/36 application compatibility G-1 
System/36 functions not supported G-10 
use 3-1 
waiting for data with ICF file, data queue 12-1 
window use 5-1 
display file attribute 
See file attribute 
Display File Description (DSPFD) command 2-7 
Display File Field Description (DSPFFD) 
command 2-7 
display file menu 
See menu display 
display form 
binary value A-24 
character value A-25 
date value A-25 
example numeric values A-24 
numeric value A-24 
time value A-25 
Display Help (DSPHELP) dialog command B-7 
Display Help Document (DSPHLPDOC) 
command 20-19 
Display Home Menu (HOME) dialog command B-9 
display I/O feedback area C-9 
Display Menu Attributes (DSPMNUA) 
command 9-16 
Display Message (MSG) dialog command B-11 
display mode 
changing 4-17 
DDS keywords ignored if changed 3-28 
definition 4-17 
displaying subfiles horizontally with 4-17 
Display Mode (DSPMOD) keyword 
description 3-27 
example for subfiles 4-17 
sample subfile display for *DS3 4-19 
sample subfile display for *DS4 4-18 
subfile use 4-17 
Display More Function Keys (MOREKEYS) dialog 
command B-10 
Display Override (DSPOVR) command 7-6 
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display panel (PANEL) tag 
example 
panel definition A-127 
overview A-122 
tags allowed table A-122 
display panel field value using dialog 
variables 17-4 
Display Program References (DSPPGMREF) 
command 2-7 
Display Right-to-Left (DSPRL) keyword 2-19 
Display Size (DSPSIZ) keyword 2-24 
display station 
acquired, releasing from I/O operations 3-49 
calculating maximum number of fields 3-39 
device description, changing for printers 2-26 
enhanced capabilities 6-4 


models 
3180-2 3-27 
3197 3-27 


5250, avoiding record format problems on 3-45 
obtaining information about 3-3 
types 5-3, 6-1 
user-defined data streams, differences for 10-1 
with UNLOCK 3-35 
display station controller, System/36 application 
compatibility G-2 
display, application 
See application display 
displaying 
list 17-8 
message 
about 8-1 
in field 8-3 
in program message queue 8-4 
on message line 8-2 
on message line using message field 8-3 
on message line when subfile control record 
written 8-2 
through subfile 8-4 
override 7-6 
panel using request processor program 17-33 
System/36 application compatibility G-4 
DL (definition list) tag 
example 
a definition list A-58 
compact definition list A-58 
overview A-57 
tags allowed table A-57 
use in help module 20-5 
DLTIGCDCT (Delete DBCS Conversion Dictionary) 
command D-19 
DLTIGCSRT (Delete DBCS Sort Table) 
command D-14 
DLTIGCTBL (Delete DBCS Font Table) command 
deleting D-10 
use D-10 


DLTMNU (Delete Menu) command 9-17 
DLTOVR (Delete Override) command 7-5 
DLTPNLGRP (Delete Panel Group) command 20-15 
DLTSCHIDXE (Delete Search Index Entry) 
command 20-17 
document, office 
comparing with panel groups and records 18-2 
creating for help 20-18 
definition for help 1-6 
examples 
HLPDOC keyword 18-10 
HLPDOC keyword with option indicators 18-11 
steps for creating sample 20-18 
help, defining for 20-18 
help, specifying for 18-9 
viewing without Help key 20-19 
double strike 17-36 
double-byte character 
basic D-4 
code scheme D-1 
DBCS-graphic D-6 
examples 
alphabetic characters coded in single-byte and 
double-byte scheme D-1 
converting and entering an entry into a 
field D-22 
copying DBCS font table to diskette D-9 
copying DBCS font table to system D-9 
copying DBCS font table to tape D-9 
extended D-4 
identifying a string of D-3, D-6 
maximum number (extended) that can be 
displayed D-6 
maximum number input fields displayed D-6 
processing extended characters D-4 
shift-control characters D-6 
shift-control characters, inserting D-6 
size D-4 
system processing of D-4 
double-byte character set 
mnemonics 6-39 
double-byte code 
effects of printing invalid D-3 
double-byte data 
basic information D-1 
considerations for using D-3 
designing application programs that process D-7 
fields, determining the length D-4 
identifying D-3 
restrictions on D-4 
where you can use D-3 
double-byte display 
effects of displaying DBCS-graphic fields D-7 
DSPATR (Display Attribute) keyword 
example source for PC value 4-24 
use 3-28 


DSPATR (Display Attribute) keyword (continued) 
with ASSUME keyword 11-1 
with program-to-system field 2-21 
DSPEDTD (Display Edit Description) 
command 2-24 
DSPFD (Display File Description) command 2-7 
DSPFFD (Display File Field Description) 
command 2-7 
DSPHELP (Display Help) dialog command B-7 
DSPHLPDOC (Display Help Document) 
command 20-19 


DSPIGCDCT (Display DBCS Conversion Dictionary) 


command D-19 
DSPMNUA (Display Menu Attributes) 
command 9-16 
DSPMOD (Display Mode) keyword 
description 3-27 
Display Mode (DSPMOD) 4-17 
example for subfiles 4-17 
sample subfile display for *~DS3 4-19 
sample subfile display for *DS4 4-18 
subfile use 4-17 
use 3-27 
DSPOVR (Display Override) command 7-6 
DSPPGMREF (Display Program References) 
command 2-7 
DSPRL (Display Right-to-Left) keyword 2-19 
DSPSIZ (Display Size) keyword 
specifying to improve performance 14-1 
use 2-24 
DTAQ (data queue) parameter 12-1 
duplicate object 
creating D-15 
duplicating window 5-11 
dynamic list column heading formatting 
example A-88 


E 


edit code 
defining your own 2-23 
definition 2-23 
description F-4 
IBM-supplied F-1 
use 2-23 
Edit Code (EDTCDE) keyword 2-23 
Edit DBCS Conversion Dictionary (EDTIGCDCT) 
command D-16 
edit description 
creating F-5 
about F-5 
example F-5 
decimal point F-4 
description F-4 
IBM-supplied F-4 
rules F-5 
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edit mask entry field 


creating 2-19 attributes for 2-18 
Edit Related Words display D-17 CUA 21-54 
edit word cursor progression for 2-17 
definition 2-23 entry displays 21-14 
Edit Word (EDTWRD) keyword 2-23 menu selection 21-10 
editing prompting B-13 
DBCS conversion dictionary D-16 protecting using Edit Masks 2-19 
EDTCDE (Edit Code) keyword 2-23 rules for displays 21-15 
EDTIGCDCT (Edit DBCS Conversion Dictionary) entry field attribute 
command D-16 creating 2-18 
EDTWRD (Edit Word) keyword 2-23 entry pointer for list 17-10 
effects of displaying DBCS-graphic fields on ERASE (Erase) keyword 
double-byte displays D-7 erasing records 3-10 
elements within a panel group 16-3 restriction with USRDSPMGT keyword G-10 
embed System/36 application compatibility G-2 
See imbed with OVERLAY keyword 3-10 
emphasis values table A-101 Erase Input (ERASEINP) keyword 
emphasizing fields 2-21 system performance considerations 14-3 
enabled selection indicator in selection list use 3-23 
example 6-29 erase-input-fields function, System/36 application 
enabling graphical user interface (GUI) compatibility G-3 
support 17-14 ERASEINP (Erase Input) keyword 
End Receive (ENDRCV) command 3-31 system performance considerations 14-3 
ending attribute character use 3-23 
definition 2-8 erasing input 3-23 
ENDRCV (End Receive) command 3-31 ERRMSG (Error Message) keyword 5-6, 8-2 
engraved key restrictions 17-14 ERRMSGID (Error Message Identifier) keyword 5-6, 
enhanced display (ENHDSP) parameter 8-2 
writing records 6-4 error 
ENHDSP (enhanced display) parameter See also major/minor return code 
writing records 6-4 See also message 
ENTER dialog command B-8 field validation 3-34 
entering recovering from 8-11 
commands that are too long 17-20 recovering from run-time 3-52 
entry dialog actions, table of CUA 21-51 while scrolling 17-15 
entry display error condition 17-15 
CUA entry field 21-53 error message 
description 21-11 dialog variables 17-3 
descriptive text area 21-16 window 5-6 
entry fields 21-14 Error Message (ERRMSG) keyword 5-6, 8-2 
examples Error Message ID (ERRMSGID) keyword 5-6 
AS/400-style 21-11 Error Message Identifier (ERRMSGID) keyword 8-2 
CUA entry field 21-53 Error Message Subfile (ERRSFL) keyword 
field prompts 21-12 example DDS source 8-4 
instruction lines 21-12 message received from 5-6 
online help information restriction with USRDSPMGT keyword G-10 
DDS considerations 21-46 use 8-4 
description 21-46 ERRSFL (Error Message Subfile) keyword 
help areas for 21-46 example DDS source 8-4 
types 21-46 message received from 5-6 
operating guidelines 21-17 restriction with USRDSPMGT keyword G-10 
possible choices information 21-16 use 8-4 
prompt areas 21-12 example 
title 21-11 atext area A-157 


accelerator key 6-22 
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example (continued) 
alternate view of list 16-15 
application formatted area A-9 
building sample display with online help 1-1 
check box 6-1 
CL programs 
program menu 9-12 
RTNPNT(*NO) for program menu, CL source 
for 9-14 
class definition A-24 
command line pop-up window 17-32 
compact definition A-58 
conditioning option A-29 
continued attribute A-1 
continued-entry field 6-43 
data description specifications (DDS) 
5250 display station problems 3-45 
ALWROL keyword 3-16 
CHRID keyword 13-1 
CLRL and OVERLAY keywords, differences 
between 3-15 
CLRL(*NO) keyword 3-14 
display file menu 9-8 
display file source 2-7 
display size, for more than one 2-24 
DSPATR(PC) keyword 4-24 
DSPMOD keyword 3-27 
DSPMOD keyword with subfiles 4-17 
ERRSFL keyword 8-4 
HLPCMDKEY keyword 18-20 
HLPCMDKEY keyword with response 
indicators 18-21 
HLPDOC keyword 18-10 
HLPDOC keyword with option indicators 18-11 
HLPPNLGRP keyword 18-7 
HLPPNLGRP keyword with option 
indicators 18-8 
HLPRCD keyword 18-13 
HLPRCD keyword with option indicators 18-14 
INZRCD and UNLOCK keywords 3-36 
message subfile 4-23 
OVERLAY and CLRL keywords, differences 
between 3-15 
program logic for subfiles 4-31 
program menu 9-11 
PUTOVR keyword 3-18 
PUTOVR keyword for repeatedly entered 
data 3-21 
PUTOVR keyword, more efficient coding 3-20 
PUTRETAIN keyword, field level 3-24 
PUTRETAIN keyword, record level 3-24 
ROLLUP, SFLSIZ, and SFLPAG keywords 4-19 
RSTDSP parameter 3-43 
secondary help 18-18 
SFLMSGID keyword 8-5 
SFLNXTCHG keyword 4-22 
SFLPAG, SFLSIZ, and ROLLUP keywords 4-19 


example (continued) 


data description specifications (DDS) (continued) 
SFLSIZ, ROLLUP, and SFLPAG keywords 4-19 
SLNO(*VAR) keyword 3-12 
subfiles for two display sizes 2-25 
UNLOCK and INZRCD keywords 3-36 
variable-length record 4-20 
data entry panel A-34, A-53 
data entry panel with nested data group A-36 
data entry panel, two-column format A-34 
data presentation panel 16-32 
data presentation panel after scrolling 16-33 
defining MNUBARDSP on application record 6-50, 
6-62 
defining MNUBARDSP on menu-bar record 6-51, 
6-65 
definition list A-58 
display with output and input fields displayed in 
response to request 2-10 
documents, office 
HLPDOC keyword 18-10 
HLPDOC keyword with option indicators 18-11 
double-byte characters 
alphabetic characters coded in single-byte and 
double-byte scheme D-1 
converting and entering entry into field D-22 
copying DBCS font table to diskette D-9 
copying DBCS font table to system D-9 
copying DBCS font table to tape D-9 
inserting shift-control characters D-6 
dynamic list column heading A-88 
edit description, creating F-5 
enabled selection indicator in selection list 6-29 
entry displays 
CUA 21-53 
typical 21-11 
formatting example A-171 
graphic image 
HTML keyword 6-85 
grid line structure 6-80 
heading tags A-65 
help modules 
command help 20-16 
imbedded 20-2 
imported 20-3 
ISCH tag 20-9 
ISCHSYN tag 20-9 
LINK tag 20-15 
panel group with 20-2 
help panel definition A-61 
horizontal selection field 6-14 
HTML keyword 
graphic image 6-85 
resolving field overlap 6-83 
hypertext link A-80 
imbedded help A-66 


Index X=-19 


example (continued) 


index search A-70 
index search synonym A-72 
information display 21-17 
key definitions A-75 
key list A-76 
left-to-right formatting on left-to-right panel A-150 
left-to-right formatting on right-to-left panel A-150 
list 
ordered A-119 
simple A-152 
translation A-159 
unordered A-165 
list actions A-95 
list area 
example, UIM source A-86 
list column groups A-87 
three layout columns A-87 
list display 
CUA 21-55 
extended action entry area 21-21 
list panel 16-14 
list part A-107 
menu area with groups A-112 
menu bar 
choices 6-7 
DDS 6-62 
panel 16-50 
UIM A-108 
menu displays 
display file menu 9-8 
message file, adding messages to 9-9 
message file, describing menu actions in 9-6 
naming help formats in message file 9-6 
program menu 9-11 
program menu, CL source for 9-12 
RTNPNT(*NO) for program menu, CL source 
for 9-14 
single choice 21-8 
using options and GO command 9-2 
menu panel 16-6 
creating 16-6 
menu source 16-9 
menu-bar choice help 6-57 
menu-bar help list 6-59 
message 
ERRSFL keyword 8-4 
SFLMSGID keyword 8-5 
message, trailer A-148 
mnemonic, not valid DDS for 6-38 
multiple-choice selection list 6-25 
multiple-selection field (UIM) A-53 
note A-117 
numeric values table A-24 
online help information 
command help 20-16 
display showing help areas 18-4 
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example (continued) 


online help information (continued) 
HLPCMDKEY keyword 18-20 
HLPCMDKEY keyword with response 
indicators 18-21 
HLPDOC keyword 18-10 
HLPDOC keyword with option indicators 18-11 
HLPPNLGRP keyword 18-7 
HLPPNLGRP keyword with option 
indicators 18-8 
HLPRCD keyword 18-13 
HLPRCD keyword with option indicators 18-14 
imbedded help modules in panel group 20-2 
imported help modules in panel group 20-3 
ISCH tag 20-9 
ISCHSYN tag 20-9 
LINK tag 20-15 
panel groups with help modules 20-2 
secondary help 18-18 
ordered list A-119 
output operation 
effect of OVERLAY and ERASE on 3-10 
overrides 
applying when compiling program 7-5 
attribute of display file 7-1 
different display file 7-3 
different display file and attributes 7-4 
panel definition A-127 
panel groups 
command help 20-16 
help modules 20-2 
HLPPNLGRP keyword 18-7 
HLPPNLGRP keyword with option 
indicators 18-8 
imbedded help modules 20-2 
imported help modules 20-3 
ISCH tag 20-9 
ISCHSYN tag 20-9 
LINK tag 20-15 
paragraph continuation A-131 
paragraph tag A-121 
parameter list A-130 
passing data 
between routing steps 11-3 
in same routing step 11-1 
print title line A-145 
program-described display file 2-27 
pull-down menu 6-18, 6-62 
PULLINPUT parameter 6-54 
push button 6-35 
radio button 6-1 
record format, replacing 3-8 
record, DDS 
HLPCMDKEY keyword 18-20 
HLPCMDKEY keyword with response 
indicators 18-21 
HLPRCD keyword 18-13 


example (continued) example (XMP) tag 


record, DDS (continued) example, formatting an example A-171 
HLPRCD keyword with option indicators 18-14 help module 20-6 
secondary help 18-18 overview A-171 
return-field (RTNFLD) parameter 6-56 EXIT (Exit Display) dialog command B-8 
roll operation 3-16 Exit Display (EXIT) dialog command B-8 
sample figure A-59 Exit key, using on menus 9-2 
sample heading A-170 exit program 
scroll bar 6-25, 6-30 commonly asked questions 17-37 
selection field 6-12, 6-13 expression 
selection list 6-26 conditional A-27, A-79 
simple list A-152 extended action entry area 
simple menu area A-112 list displays 21-24 
single-choice selection field choice help 6-57 extended alphabetics 
single-choice selection list 6-25 definition 13-1 
SLNO (Starting Line Number) keyword 3-12 extended character 
subfile processing D-4 
*DS3 mode display 4-19 what happens when not processed D-4 
*DS4 mode display 4-18 extended help 
DSPATR(PC) keyword 4-24 definition 18-3, 19-2 
DSPMOD keyword 4-17 Extended Help (EXTHELP) dialog command B-9 
message subfile 4-23 extended help heading (XH1 through XH4) tag 
program logic for subfiles 4-31 example, sample heading A-170 
ROLLUP, SFLSIZ, and SFLPAG keywords 4-19 formatting rules A-170 
sample display for changing information 4-2 overview A-170 
sample display for display only 4-1 use in help module 20-4 
sample display for input only 4-2 externally described data 
sample display for task combination 4-2 advantages of 2-3 
sample display with selection 4-1 definition 2-3 
sample displays when rolling two or more use 2-3 
records 4-28 EXTHELP (Extended Help) dialog command B-9 
SFLNXTCHG keyword 4-22 
SFLPAG, SFLSIZ, and ROLLUP keywords 4-19 F 
SFLSIZ, ROLLUP, and SFLPAG keywords 4-19 
variable-length record 4-20 FA 8=More indexes 
vertical and horizontal, displayed at same removing access 
time 4-16 feedback area 
suppressed selection indicator in pull-down common 3-3 
menu 6-21 error information 3-4 
suppressed selection indicator in selection file-dependent 3-3 
field 6-18 function keys 2-12 
title citation A-13 get attributes C-12 
translation list A-159 VO 
truth table A-162 common C-6 
two presentation areas definition 3-3 
data items A-35 display C-9 
menu area A-36 for function keys 2-12 
unavailable choice 6-37 open 
unformatted lines A-77 definition 3-3 
unordered list A-165 device definition list C-4 
valid DDS for mnemonic 6-38 individual descriptions C-1 
validity checking A-12 field 
vertical multiple-choice selection field 6-14 attribute 
vertical single-choice selection field 6-13 defining 2-18 
window title 5-10 attributes, System/36 application compatibility G-3 
window use 5-15 calculating maximum number for display 
station 3-39 
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field (continued) 
character, maximum length 2-11 
characteristics of 2-2 
choice entry, Common User Access 21-53 
color 2-22 
constant 2-10 
cursor progression 
defining 2-17 
default values, specifying 3-26 
defining 
attribute 2-18 
cursor progression 2-17 
definition 2-2 
display 2-7 
displaying 2-8 
emphasizing 2-21 
entry 
See entry field 


erasing unprotected input and output/input 3-23 


hidden 2-9 
input 2-9 
input and output, displayed in response to 
request 2-10 
input-capable, limitations on number of 3-39 
keeping on display 3-23 
list 21-24 
maximum number in record format 2-10 
menu selection entry 21-10 
message 2-10 
numeric 
maximum length 2-11 
output 2-9 
output/input 2-9 
overriding attributes or content of 3-18 
previously described 2-11 
program-to-system 
understanding how to use 2-10 
with DSPATR keyword 2-21 
record format 2-9 
reference 2-11 
validation errors 3-34 
zoned decimal, maximum length 2-11 
field (*“FLD) special value 6-57 
field attribute character 2-8 
Field Cursor Progression (FLDCSRPRG) 
keyword 2-17 
Field Exit (CHECK(FE)) keyword 6-18 
field location 
input and output records 2-9 
when to specify 2-11 
field prompt, entry displays 21-12 
field value for display panel using dialog 
variables 17-4 
field-exit processing 
backward 6-49 
forward 6-49 
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field-level description 
definition 2-2 
use 2-2 
field, graphic A-6 
FIG (figure) tag 
example, sample figure A-59 
overview A-59 
use in help module 20-6 
figure (FIG) tag 
example, sample figure A-59 
overview A-59 
use in help module 20-6 


file 

DBCS 
diskette D-5 
display D-5 
ICF D-5 
printer D-5 
tape D-5 

definition 2-3 

display 


See display file 
shared in job 
close operation for 3-52 
input/output operation for 3-51 
open operation for 3-51 
source 1-2 
file attribute 
building 7-1 
overriding 
along with display file name in HLL 
programs 7-3 
display files in HLL programs 7-1 
file description 
changing 
reasons for 2-2 
with the CHGDSPF command 2-5 
creating for display file 2-4 
definition 1-1 
detecting changes in 2-6 
determining 2-2 
file redirection 
definition 7-6 
different file types 7-6 
level checking 7-6 
same file types 7-6 
table of defaults for combinations 7-7 
valid for input and output 7-7 
file resource 
how allocated 3-1 
file-dependent feedback area 3-3 
file-level description 2-3 
FLDCSRPRG (Field Cursor Progression) 
keyword 2-17 
folding 
list panel 17-26 


folding (continued) 
multiple panels when EXIT requested 17-24 
when EXIT requested 17-24 
font 
highlighting 17-36 
font table, DBCS 
description of D-8 
determining existence D-8 
restoring from tape or diskette D-9 
saving onto diskette D-9 
format, record 
See record format 
formatting 
bidirectional considerations A-80 
column data A-99 
display form 
binary value A-24 
character value A-25 
date value A-25 
time value A-25 
example A-171 
function keys 17-20 
IGC (ideographic characters) 
BOTINST (bottom instruction) tag A-10 
DATAC (data item choices) tag A-38 
PDFLDC (pull-down field choice) tag A-136 
TOPINST (top instruction) tag A-161 
numeric value 
example values table A-24 
panel 
concepts 17-22 
user control 17-24 
panels 17-22 
printed 
information area A-69 
list area A-86 
forward field-exit processing 6-49 
full screen mode 
help information A-61 
function key 
assignments, table 21-38 
common assignments on AS/400-style 
displays 21-38 
CUA entry dialog actions, table of 21-51 
DDS keywords for 2-11 
defining 
inDDS 2-11 
in UIM 17-20 
formatting in UIM 17-20 
handling in VIM 17-21 
optional for AS/400-style displays, table of 21-8 
required for AS/400-style displays, table of 21-8 
retain command, System/36 application 
compatibility G-9 
scrolling in UIM 17-15 
System/36 application compatibility G-7 


function key (continued) 
VARUPD value 17-21 
function key area 
CUA 21-52 
menu displays, single-choice 21-8 
function key area help 19-15 
function, built-in 
CHKOBu (check object) A-28, A-79 
CHKUSRCLS (check user class) A-28, A-80 


G 


get-atiributes feedback area C-12 
get-attributes operation 
definition 3-4 
ILE C function for 3-49 
ILE COBOL statement for 3-49 
ILE RPG operation for 3-49 
table of information available from 3-4 
get-next-changed operation 
definition 4-14 
get-next-changed operation for subfiles 
BASIC statement for 4-15 
ILE C function for 4-15 
ILE COBOL statement for 4-15 
ILE RPG operation for 4-15 
get-relative operation 
definition 4-13 
get-relative operation for subfiles 
BASIC statement for 4-15 
ILE C function for 4-15 
ILE COBOL statement for 4-15 
ILE RPG operation for 4-15 
GETRETAIN (Get Retain) keyword 3-36 
GO (Go to Menu) command 
generic menu specification 9-16 
use 9-1 
Go to Menu (GO) command 
generic menu specification 9-16 
use 9-1 
Grant Object Authority (GRTOBJAUT) 
command D-15 
graphical user interface (GUI) 
support 17-14 
graphics 
field A-6 
literal A-6 
GRDATR (Grid Line Attribute) keyword 6-80 
GRDBOX (Grid Box) keyword 6-80 
GRDCLR (Grid Clear) 6-80 
GRDLIN (Grid Line) 6-80 
GRDRCD (Grid Record) 6-80 
Grid Box (GRDBOX) keyword 6-80 
Grid Clear (GRDCLR) 6-80 
Grid Line (GRDLIN) 6-80 


Index 


Grid Line Attribute (GRDATR) keyword 6-80 
grid line structure 
definition 6-79 
example, DDS_ 6-80 
hardware requirements 6-82 
overview 6-79 
window 6-81 
Grid Record (GRDRCD) 6-80 
group object, panel A-2 
GRTOBJAUT (Grant Object Authority) 
command D-15 
GUI (graphical user interface) 
support 17-14 
guideline 
CUA, single selection field operation 21-53 
message 21-49 
operating 
entry displays 21-17 
information displays 21-21 
list display 21-26 
menu displays 21-10 


H 


H specification 
definition 18-4 
effect on help-list updating 18-16 
entering in DDS source 18-4 
order in DDS source 18-4 
paging order 18-16 

H1 through H4 (headings) 
example 

heading tags A-65 

help module 20-4 
overview A-65 

handle on list entry 17-9 


handling function keys and VARUPD value 17-21 


header area 
defining 17-36 
heading (H1 through H4) tag 
example 
heading tags A-65 
overview A-65 
use in help module 20-4 
heading, column 21-24 
help 
choice-level 6-56 
data area 19-8 
defining for application 6-56 
displayed in window 5-7, 5-9 
field 6-59 
function key area 19-15 
item specific 6-58 
list area 19-3 
menu area 19-6 
menu bar area 19-13 
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help (continued) 
panels A-3 
HELP (help module) tag 
example, help panel definition A-61 
overview A-60 
placement in UIM source 20-2 
UIM source showing panel groups with help 
modules 20-2 
HELP (Help) keyword 
enabling the Help key 18-2 
function key use 2-12 
specifying alternative 2-13 
System/36 application compatibility G-7 
help area 
See online help information 
Help Area (HLPARA) keyword 18-4 
help boundary 
definition 18-17 
Help Boundary (HLPBDY) keyword 
secondary help 18-18 
use 18-17 
Help Command Key (HLPCMDKEY) keyword 
restriction with USRDSPMGT keyword G-10 
use 18-20 
HELP dialog command _ B-9 
help display 
See online help information 
Help Document (HLPDOC) keyword 
for specifying the document name_ 18-9 
with HLPRCD and HLPPNLGRP_ 18-11 
with option indicators 18-11 
Help Exclude (HLPEXCLD) keyword 18-6 
help for field 6-59 
Help Full (HLPFULL) keyword 18-6 
help group 
definition 18-17 
help information 
See online help information 
Help InfoSeeker (HLPSHELF) keyword 18-6 
Help key 19-1 
See also ALTHELP (Alternate Help) keyword 
See also HELP (Help) keyword 
enabling 18-2 
results when pressed 18-1 
returning to program after pressing 18-20 
returning to program without pressing 18-22 
help list 
defining for application 6-58 
definition 18-16 
help module 


contained in different help panel group, using 20-3 


definition 20-2 
emphasizing and formatting text within 20-4 
examples 

command help 20-16 

imbedded 20-2 

imported 20-3 


help module (continued) 
examples (continued) 
ISCH tag 20-9 
ISCHSYN tag 20-9 
LINK tag 20-15 
panel group with 20-2 
headings, adding 20-4 
highlighting text 20-4 
hypertext 20-13 
linking 20-13 
making lists 20-5 
names 20-2 
organizing panel group with 20-2 
paragraphs and notes, defining 20-4 
programming keywords and variables, 
identifying 20-5 
structured text, indicating 20-6 
using more than once 20-2 
help module (HELP) tag 
example, help panel definition A-61 
overview A-60 
placement in UIM source 20-2 
Help Panel Group (HLPPNLGRP) keyword 
use 18-6 
with HLPRCD and HLPDOC keywords 18-8 
with option indicators 18-8 
Help Record (HLPRCD) keyword 
with HLPDOC keyword in same file 18-15 
with HLPPNLGRP keyword in same file 18-12 
with option indicators 18-13 
Help Return (HLPRTN) keyword 
returning to your program after help 18-22 
System/36 application compatibility G-7 
Help Search Index (HLPSCHIDX) keyword 18-6 
Help Sequencing (HLPSEQ) keyword 18-17 
help sublist 
definition 18-17 
help text 
See online help information 
help text displayed according to cursor 
position 17-17 
Help Title (HLPTITLE) keyword 18-6 
HELPHELP dialog command _ B-9 
HELPIDX dialog command _ B-9 
hexadecimal data A-6 
hidden field 
definition 2-9 
using 2-9 
hierarchy, index search 20-11 
high-level language (HLL) 
overriding display file attributes in programs 7-1 
overriding display file names and attributes in pro- 
grams 7-3 
overriding display file names in programs 7-3 
recognizing the I/O requests supported by 3-49 
System/36 application compatibility G-1 


highlight phrases table A-63 
highlighted phrase (HPO through HP9) tag 
overview A-63 
use in help module 20-4 
highlighting 
selection characters A-9, A-155 
highlighting and fonts 17-36 
HLL (high-level language) 
overriding display file attributes in programs 7-1 
overriding display file names and attributes in pro- 
grams 7-3 
overriding display file names in programs 7-3 
recognizing the I/O requests supported by 3-49 
System/36 application compatibility G-1 
HLPARA (Help Area) keyword 18-4 
HLPBDY (Help Boundary) keyword 
secondary help 18-18 
use 18-17 
HLPCMDKEY (Help Command Key) keyword 
response indicators, sample source with 18-21 
restriction with USRDSPMGT keyword G-10 
sample DDS source 18-20 
use 18-20 
HLPDOC (Help Document) keyword 
examples 
option indicators, sample source with 18-11 
sample DDS source 18-10 
specifying the document name_ 18-9 
with HLPRCD and HLPPNLGRP keywords 18-11 
with option indicators 18-11 
HLPEXCLD (Help Exclude) keyword 18-6 
HLPFULL (Help Full) keyword 18-6 
HLPPNLGRP (Help Panel Group) keyword 
example 
option indicators, sample source with 18-8 
sample DDS source 18-7 
use 18-6 
with HLPRCD and HLPDOC keywords’ 18-8 
with option indicators 18-8 
HLPRCD (Help Record) keyword 
example 
option indicators, sample source with 18-14 
sample DDS source 18-13 
secondary help 18-18 
with HLPDOC keyword in same file 18-15 
with HLPPNLGRP keyword in same file 18-12 
with option indicators 18-13 
HLPRTN (Help Return) keyword 
returning to your program after help 18-22 
System/36 application compatibility G-7 
HLPSCHIDX (Help Search Index) keyword 18-6 
HLPSEQ (Help Sequencing) keyword 18-17 
HLPSHELF (Help InfoSeeker) keyword 18-6 
HLPTITLE (Help Title) keyword 18-6 
HOME (Display Home Menu) dialog command _ B-9 
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HOME (Home) keyword 2-12 
horizontal selection field 
cursor movement 6-16, 6-17 
example 6-14 
HPO through HP9 (highlighted phrase) tag 
overview A-63 
use in help module 20-4 
HTML (Hypertext Markup Language) keyword 
inserting 6-82 
resolving field overlap 6-83 
examples 6-83 
restrictions 6-87 
hypertext 
See also online help information 
definition 20-13 
hypertext link 
example A-80 
hypertext link definition (LINK) tag 
conditional expressions 
CHKOBzy built-in function A-79 
CHKUSRCLS (check user class) built-in 
function A-80 
example, hypertext link A-80 
overview A-78 
placement in UIM source 20-15 
Hypertext Markup Language (HTML) keyword 
resolving field overlap 6-83 
using 6-82 
hypertext reference phrase 
See also online help information 
definition 20-14 


VO feedback area 
common C-6 
contents 3-3 
definition 3-3 
display C-9 
/O operation 
acquiring a display station for 3-2 
locking keyboard and positioning cursor 3-41 
mapping to HLL operations 
CL commands 3-49 
ILE C functions 3-49 
ILE COBOL statements 3-49 
ILE RPG operations 3-49 
obtaining information about 3-3 
releasing an acquired display station from 3-49 
requesting 
for subfile control record formats 4-15 
for subfile record formats 4-12 
for subfiles 4-12 
I/O request 
high-level languages, table of subfile 4-15 
supported by high-level languages 3-49 
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ICF file 
DBCS D-5 
file entry field attributes 12-1 


waiting for data with display file, data queue 12-1 


identifier fields for menu displays 21-34 
identifier, level 2-6 
ideographic characters (IGC) 
formatting 
BOTINST (bottom instruction) tag A-10 
DATAC (data item choices) tag A-38 
PDFLDC (pull-down field choice) tag A-136 
TOPINST (top instruction) tag A-161 
IGC (ideographic characters) 
formatting 
BOTINST (bottom instruction) tag A-10 
DATAC (data item choices) tag A-38 
PDFLDC (pull-down field choice) tag A-136 
TOPINST (top instruction) tag A-161 


IGCALTTYP (Alternative Data Type) keyword D-5 


ILE C functions 
I/O requests for subfiles 4-15 
mapping to I/O operations 3-49 
ILE COBOL statement 
I/O requests for subfiles 4-15 
mapping to I/O operations 3-49 
ILE RPG operation 
I/O requests for subfiles 4-15 
mapping to I/O operations 3-49 
imbed help (IMHELP) tag 
example, imbedded help A-66 
overview A-66 
placement in UIM source 20-2 
imbedding 
nesting source files A-6 
imbedding source files 
nesting imbeds A-6 
imbedding UIM source files A-6 
IMHELP (imbed help) tag 
example, imbedded help A-66 
overview A-66 
placement in UIM source 20-2 
UIM source showing panel groups using 20-2 
UIM source showing panel groups with help 
modules 20-2 
IMPORT (import) tag 
overview A-67 
placement in UIM source 20-3 
UIM source showing panel groups using 20-3 
improving 
productivity with UIM 15-1 
system performance with displays 14-1 
improving productivity with UIM 15-1 
inactive subfile record 
definition 4-4 
incorrect characters in dialog variable 17-4 


incorrect display characters 17-4 
incorrect printer characters 17-4 
INDARA (Indicator Area) keyword 2-15 
index search 
See also online help information 
F18=More indexes 
removing access 19-5 
index search (ISCH) tag 
parameter list A-70 
placement in UIM source 20-9 
index search function 
See online help information 
index search hierarchy 20-11 
Index search key (F11) 20-6 
index search subtopic (ISCHSUBT) tag 
parameter list A-71 
placement in UIM source 20-11 
index search synonym (ISCHSYN) tag 
parameter list A-72 
placement in UIM source 20-9 
indicator 
definition 2-14 
option 
definition 2-14 
for display files 2-14 
passing information via 2-14 
response 
definition 2-12 
for display files 2-14 
selection 
in pull-down menu 6-20 
in selection field 6-17 
in selection list 6-28 
setting off 2-15 
setting when data is changed 3-36 
types for display files 2-14 
Indicator Area (INDARA) keyword 2-15 
INFO (information area) tag 
overview A-68 
print formatting considerations A-69 
information area 
printed A-69 
scrolling 17-16 
information area (INFO) tag 
overview A-68 
print formatting considerations A-69 
information area scrolling 17-16 
information display 
CUA 21-55 
description 21-17 
example 21-17 
instruction lines 21-20 
location information 21-19 
online help information 
DDS considerations 21-47 
description 21-47 
help areas for 21-47 


information display (continued) 


operating guidelines 21-21 

prompt areas 21-19 

titles 21-19 
information, help 

See online help information 
information, location 

See location information, displays 
information, online help 

See online help information 
InfoSeeker 

See online help information 
initial menu 

definition 9-3 


Initialize Diskette (INZDKT) command D-9 
Initialize Record (INZRCD) keyword 3-35 


initializing 
list display 17-8 
output/input fields 3-29 
initializing list 17-8 
input data 
from the display 
how the system reads 3-40 
reading 3-33 
reading invited 3-31 
handling negative numeric 3-40 
inviting 
from CL programs 3-30 
to the display 3-30 
keeping 3-36 
reading while writing output 3-40 
System/36 application compatibility G-2 
input field 
definition 2-9 


displayed characters on DBCS display D-6 


erasing 3-23 
example, display with output and 2-10 


improving performance when sending records 


with 14-2 

using 2-9 
input file 

defining 2-28 
input not waited for, canceling 3-41 
input operation 


effect of INZRCD and UNLOCK keywords on 3-36 


input-capable field 
limitations on number of 3-39 
input-only file 
defining 2-28 
input/output feedback area 
common C-6 
contents 3-3 
definition 2-12, 3-3 
display C-9 
input/output operation 
acquiring a display station for 3-2 


Index 
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input/output operation (continued) 
files shared ina job 3-51 
locking keyboard and positioning cursor 3-41 
mapping to HLL operations 
CL commands 3-49 
ILE C functions 3-49 
ILE COBOL statements 3-49 
ILE RPG. operations 3-49 
mapping to I/O operations 3-49 
obtaining information about 3-3 
releasing an acquired display station from 3-49 
requesting 
for subfile control record formats 4-15 
for subfile record formats 4-12 
for subfiles 4-12 
input/output request 
high-level languages, table of subfile 4-15 
supported by high-level languages 3-49 
inserting 
entry from list display 17-10 
HTML tags 6-82 
inserting entry from list 17-10 
instruction line 
entry displays 21-12 
information displays 21-20 
list display 21-22 
menu displays, single-choice 21-9 
interaction 
between menu bar and application 6-50 
between menu bar and pull-down menu 6-60 
interactive response time for list displays 17-11 
interpretation of command line 17-19 
INVITE (Invite) keyword 
system performance considerations 14-3 
use 3-30 
invite operation 
CL command for 3-49 
definition 3-30 
ILE C function for 3-49 
ILE COBOL statement for 3-49 
ILE RPG operation for 3-49 
system performance considerations 14-3 
invited input, reading from the display 3-31 
INZDKT (Initialize Diskette) command D-9 
INZINP (Initialize Input) keyword 
performance considerations 14-3 
INZRCD (Initialize Record) keyword 
example with UNLOCK keyword 3-36 
use 3-35 
ISCH (index search) tag 
parameter list A-70 
placement in UIM source 20-9 
ISCHSUBT (index search subtopic) tag 
parameter list A-71 
placement in UIM source 20-11 
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ISCHSYN (index search synonym) tag 
parameter list A-72 
placement in UIM source 20-9 
item-specific help 6-58 


job 
close operation for files shared in 3-52 
input/output operation for files shared in 3-51 
open operation for files shared in 3-51 


K 
KEEP (Keep) keyword 
considerations 11-1 
example DDS source 11-3 
restriction with USRDSPMGT keyword G-10 
sharing file between programs 11-1 
System/36 application compatibility G-2 
key 
Cancel and Exit, using on menus 9-2 
CAnn and CFnn, defining 2-12 
CFnn (command function), validity 
considerations 3-45 
command 
defining 2-12 
validity considerations 3-45 
command attention (CAnn) 2-12 
command function (CFnn) 2-12 
function 
defining 2-11 
System/36 application compatibility G-7 
key assignments, common 
See common key assignments 
key definition 
example A-75 
key interaction for menu bars and pull-down 
menus 6-60 
key list (KEYL) tag 
example, key list A-76 
overview A-76 
tags allowed table A-76 
key list item (KEYI) tag 
example, key definitions A-75 
overview A-74 
keyboard 
locking 3-10 
locking during I/O operations 3-41 
unlocking while the program is processing 
data 3-35 
keyboard function 
continued-entry field 6-44 
KEYI (key list item) tag 
example, key definitions A-75 
overview A-74 


KEYL (key list) tag 

example, key list A-76 

overview A-76 

tags allowed table A-76 
KEYSHELP dialog command _ B-10 
keyword, DDS 

Alternative Help (ALTHELP) 2-13 

ALTHELP (Alternative Help) 2-13 


ALTPAGEDWN (Alternative Page Down) 2-13 


ALTPAGEUP (Alternative Page Up) 2-13 
ALWROL (Allow Roll) 

example 3-16 

use 3-16 
ASSUME (Assume) 

example DDS source 11-1, 11-3 

use 11-1 

with DFT keyword 11-1 
CAnn (Command Attention) 2-11 
CFnn (Command Function) 2-11 
CHANGE (Change) 3-36 
CHECK (Check) 

AB value 3-37 

description 2-16 

M10 value 3-37 

M11 value 3-37 

ME value 3-37 

MF value 3-37 

VN value 3-37 

VNE value 3-37 
CHRID (Character Identifier) keyword 13-1 
CLEAR (Clear) 2-11 
CLRL (Clear Line) 3-13 

example with *NO value 

example with OVERLAY 3-15 


system performance considerations 14-2 


coding, more efficient 3-20 
COLOR (Color) 2-22 
COMP (Comparison) 3-37 
CSRINPONLY (Cursor Input Only) 2-16 
CSRLOC (Cursor Location) 3-28 
Cursor Input Only (CSRINPONLY) 2-16 
data, repeatedly entered 3-21 
DFT (Default) 

description 3-26 

with ASSUME keyword 11-1 
DFTVAL (Default Value) 3-26 
Display Attribute (DSPATR) 

adding color to fields with 2-22 

emphasizing fields with 2-21 

PC value 3-28, 4-24 

table of values for 2-21, 2-22 

with ASSUME keyword 11-1 


Display Right-to-Left (DSPRL) keyword 2-19 


Display Size (DSPSIZ) 
use 2-24 
DSPATR (Display Attribute) 
adding to color to fields with 2-22 


keyword, DDS (continued) 


DSPATR (Display Attribute) (continued) 
emphasizing fields with 2-21 
PC value 3-28, 4-24 
table of color effects 2-22 
table of values for 2-21 
with ASSUME keyword 11-1 
DSPMOD (Display Mode) 
description 3-27 
example for subfiles 4-17 
subfile display for *DS3 4-19 
subfile display for *DS4 4-18 
DSPRL (Display Right-to-Left) keyword 2-19 
DSPSIZ (Display Size) 
specifying to improve performance 14-1 
use 2-24 
EDTCDE (Edit Code) 2-23 
EDTWRD (Edit Word) 2-23 
ERASE (Erase) 
effect on output operation 3-10 
example of effects with OVERLAY 3-10 
Erase Input (ERASEINP) 
system performance considerations 14-3 
use 3-23 
ERASEINP (Erase Input) 
system performance considerations 14-3 
use 3-23 
ERRMSG (Error Message) 8-2 
ERRMSGID (Error Message Identifier) 8-2 
Error Message (ERRMSG) _ 8-2 
Error Message Identifier (ERRMSGID) 8-2 
Error Subfile (ERRSFL) 
description 8-4 
example DDS source 8-4 
ERRSFL (Error Subfile) 
description 8-4 
example DDS source 8-4 
field 
color (table) 2-22 
emphasizing (table) 2-21 
Field Cursor Progression (FLDCSRPRG) 2-17 
field level 3-24 
FLDCSRPRG (Field Cursor Progression) 2-17 
function keys, defining with 2-11 
GETRETAIN (Get Retain) 3-36 
GRDATR (Grid Line Attribute) 6-80 
GRDBOX (Grid Box) 6-80 
GRDCLR (Grid Clear) 6-80 
GRDLIN (Grid Line) 6-80 
GRDRCD (Grid Record) 6-80 
Grid Box (GRDBOX) 6-80 
Grid Clear (GRDCLR) 6-80 
Grid Line (GRDLIN) 6-80 
Grid Line Attribute (GRDATR) 6-80 
Grid Record (GRDRCD) 6-80 
H specifications 
See H specifications 
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keyword, DDS (continued) 
HELP (Help) 
enabling Help key 18-2 
function key use 2-12 
Help Area (HLPARA) 18-4 
Help Boundary (HLPBDY) 
use 18-17 
Help Command Key (HLPCMDKEY) 
use 18-20 
Help Document (HLPDOC) 
description 18-9 
with option indicators 18-11 
Help Exclude (HLPEXCLD) 18-6 
Help Full (HLPFULL) 18-6 
Help InfoSeeker (HLPSHELF) 18-6 
Help Panel Group (HLPPNLGRP) 
description 18-6 
with option indicators 18-8 
Help Record (HLPRCD) 
description 18-12 
with option indicators 18-13 
Help Return (HLPRTN) 18-22 
Help Search Index (HLPSCHIDX) 18-6 
Help Sequencing (HLPSEQ) 18-17 
Help Title (HLPTITLE) 18-6 
HLPARA (Help Area) 18-4 
HLPBDY (Help Boundary) 
secondary help 18-18 
use 18-17 
HLPCMDKEY (Help Command Key) 


response indicators, sample source with 18-21 


sample DDS source 18-20 

use 18-20 
HLPDOC (Help Document) 

description 18-9 

option indicators, sample source with 

sample DDS source 18-10 

with option indicators 18-11 
HLPEXCLD (Help Exclude) 18-6 
HLPFULL (Help Full) 18-6 
HLPPNLGRP (Help Panel Group) 

description 18-6 

option indicators, sample source with 

sample DDS source 18-7 

with option indicators 18-8 
HLPRCD (Help Record) 

description 18-12 

option indicators, sample source with 

sample DDS source 18-13 

secondary help 18-18 

with option indicators 18-13 
HLPRTN (Help Return) 18-22 
HLPSCHIDX (Help Search Index) 18-6 
HLPSEQ (Help Sequencing) 18-17 
HLPSHELF (Help InfoSeeker) 18-6 
HLPTITLE (Help Title) 18-6 
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18-11 


18-14 


keyword, DDS (continued) 
HOME (Home) 2-12 
HTML (Hypertext Markup Language) 
resolving field overlap 6-83 
restrictions 6-87 
use 6-82 
INDARA (Indicator Area) 2-15 
Indicator Area (INDARA) 2-15 
Initialize Record (INZRCD) 
use 3-35 
INVITE (Invite) 
description 3-30 
system performance considerations 14-3 


INZINP (Initialize Input), system performance consid- 


erations 14-3 
INZRCD (Initialize Record) 
example with UNLOCK keyword 3-36 
use 3-35 
KEEP (Keep) 
description 11-1 
example DDS source 11-3 
keywords ignored if display modes are 
changed 3-28 
LOCK (Lock) 3-42 
MDTOFF (Modified Data Tag Off) 3-23 
MOUBTN (Programmable Mouse Button) 6-69 
MSGALARM (Message Alarm) 8-7 
MSGID (Message Identifier) 8-3 
OVERLAY (Overlay) 
description 3-10 
effect on output operation 3-10 
example of effects with ERASE 3-10 
example with CLRL 3-15 
system performance considerations 14-3 
Override Attribute (OVRATR) 
system performance considerations 14-2 
use 3-18 
Override Data (OVRDTA) 3-20 
system performance considerations 14-2 
OVRATR (Override Attribute) 
system performance considerations 14-2 
use 3-18 
OVRDTA (Override Data) 3-20 
system performance considerations 14-2 
Page Down (PAGEDOWN) 2-12 
Page Up (PAGEUP) 
defining 2-12 
PAGEDOWN (Page Down) 2-12 
PAGEUP (Page Up) 2-12 
PASSRCD (Passed Record) 11-3 
PRINT (Print) 
enabling 2-25 
for function key 2-12 
results available (table) 2-25 
Programmable Mouse Button (MOUBTN) 6-69 
PSHBTNCHC (Push Button Choice) 6-35 


keyword, DDS (continued) 
PSHBTNELD (Push Button Field) 6-35 
Push Button Choice (PSHBTNCHC) 6-35 
Push Button Field (PSHBTNFLD) 6-35 
Put with Explicit Override (PUTOVR) 
description 3-18 
system performance considerations 14-2 
Put-Retain (PUTRETAIN) 
description 3-23 
PUTOVR (Put with Explicit Override) 
description 3-18 
example 3-18 
system performance considerations 14-2 
PUTRETAIN (Put-Retain) 
description 3-23 
for record level 3-24 
RANGE (Range) 3-37 
Return Cursor Location (RTNCSRLOC) 3-29 
Roll Down (ROLLDOWN) 
defining 2-12 
response indicators for 2-15 
Roll Up (ROLLUP) 
example with SFLSIZ and SFLPAG 4-19 
for function key 2-12 
improving subfile performance 14-1 
response indicators for 2-15 
ROLLDOWN (Roll Down) 
defining 2-12 
response indicators for 2-15 
ROLLUP (Roll Up) 
example with SFLSIZ and SFLPAG 4-19 
for function key 2-12 
improving subfile performance 14-1 
response indicators for 2-15 
RTNCSRLOC (Return Cursor Location) 3-29 
Set Off (SETOF or SETOFF) 2-15 
SETOF or SETOFF (Set Off) 2-15 
SFL (Subfile) 4-3 
SFLCHCCTL (Subfile Choice Control) 6-26 
SFLCLR (Subfile Clear) 4-4 
SFLCSRPRG (Subfile Cursor Progression) 2-18 
SFLCSRRRN (Subfile Cursor Relative Record 
Number) 3-29 
SFLCTL (Subfile Control) 4-3 
SFLDLT (Subfile Delete) 4-4 
SFLDROP (Subfile Drop) 4-4 
SFLDSP (Subfile Display) 4-3 
SFLDSPCTL (Subfile Display Control) 4-4 
SFLEND (Subfile End) 4-4 
SFLENTER (Subfile Enter) 4-4 
SFLFOLD (Subfile Fold) 4-4 
SFLINZ (Subfile Initialize) 4-4 
SFLLIN (Subfile Line) 4-4 
SFLMODE (Subfile Mode) 3-29 
SFLMSG (Subfile Message) 
defining 4-4 
description 4-4 


keyword, DDS (continued) 


SFLMSG (Subfile Message) (continued) 
displaying on message line when subfile control 
record written 8-2 
SFLMSGID (Subfile Message Identifier) 
defining 4-4 
description 4-4 
displaying on message line when subfile control 
record written 8-2 
sample DDS 8-5 
SFLMSGKEY (Subfile Message Key) 
description 4-4 
displaying messages from a program message 
queue 8-4 
SFLMSGRCD (Subfile Message Record) 
description 4-4 
displaying messages from a program message 
queue 8-4 
SFLNXTCHG (Subfile Next Changed) 
description 4-4 
example 4-22 
SFLPAG (Subfile Page) 
example with ROLLUP and SFLSIZ 4-19 
use in subfile control record format 4-3 
SFLPGMQ (Subfile Program Message Queue) 
description 4-4 
displaying messages from a program message 
queue 8-4 
SFLRCDNBR (Subfile Record Number) 
description 4-4 
improving subfile performance 14-1 
SFLRNA (Subfile Records Not Active) 4-4 
SFLROLVAL (Subfile Roll Value) 4-4 
SFLRTNSEL (Subfile Return Selected Choice) 6-27 
SFLSCROLL (Subfile Scroll) 6-28 
SFLSIZ (Subfile Size) 
example with ROLLUP and SFLPAG 4-19 
use in subfile control record format 4-3 
SFLSNGCHC (Subfile Single-Choice 
Selection) 6-26 
SLNO (Starting Line Number) 
example with *VAR value 3-12 
use 3-11 
Starting Line Number (SLNO) 
example with *VAR value 3-12 
use 3-11 
Subfile Choice Control (SFLCHCCTL) 6-26 
Subfile Clear (SFLCLR) 4-4 
Subfile Control (SFLCTL) 4-3 
Subfile Cursor Progression (SGFLCSRPRG) 2-18 
Subfile Cursor Relative Record Number 
(SFLCSRRRN) 3-29 
Subfile Delete (SFLDLT) 4-4 
Subfile Display (SFLDSP) 4-3 
Subfile Display Control (SGFLDSPCTL) 4-4 
Subfile Drop (SFLDROP) 4-4 
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keyword, DDS (continued) 
Subfile End (SFLEND) 4-4 
Subfile Enter (SFLENTER) 4-4 
Subfile Fold (SFLFOLD) 4-4 
Subfile Initialize (SFLINZ) 4-4 
Subfile Line (SFLLIN) 4-4 
Subfile Message (SFLMSG) 
defining 4-4 
description 4-4 
displaying on message line when subfile control 
record written 8-2 
Subfile Message Identifier (SFLMSGID) 
defining 4-4 
description 4-4 
displaying on message line when subfile control 
record written 8-2 
sample DDS 8-5 
Subfile Message Key (SFLMSGKEY) 
description 4-4 
displaying messages from a program message 
queue 8-4 
Subfile Message Record (SFLMSGRCD) 
description 4-4 
displaying messages from a program message 
queue 8-4 
Subfile Mode (SFLMODE) 3-29 
Subfile Next Changed (SFLNXTCHG) 
description 4-4 
example 4-22 
Subfile Page (SFLPAG) 
example with ROLLUP and SFLSIZ 4-19 
use in subfile control record format 4-3 
Subfile Program Message Queue (SFLPGMQ) 
description 4-4 
displaying messages from a program message 
queue 8-4 
Subfile Record Number (GFLRCDNBR) 
description 4-4 
improving subfile performance 14-1 
Subfile Records Not Active (SFLRNA) 4-4 


Subfile Return Selected Choice (SFLRTNSEL) 6-27 


Subfile Roll Value (SFLROLVAL) 4-4 
Subfile Scroll (SGFLSCROLL) 6-28 
Subfile Single-Choice Selection 
(SFLSNGCHC) 6-26 
Subfile Size (SFLSIZ) 
example with ROLLUP and SFLPAG 4-19 
use in subfile control record format 4-3 
UNLOCK (Unlock) 
effects on input operation 3-36 
example with INZRCD keyword 3-36 
unlocking while program is processing data 3-35 
USRDFN (User-Defined) 10-1 
validity-checking 3-37 
VALNUM 3-37 
VALUES (Values) 3-37 
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keyword, DDS (continued) 
Window Title (WDWTITLE) 5-9 
Word Wrap (WRDWRAP) 2-20, 6-43 


L 


layout 
title lines table A-143 
layout and positions summary table A-105, A-106 
left-to-right formatting on a left-to-right panel 
example A-150 
left-to-right formatting on a right-to-left panel 
example A-150 
level identifier 
changes in 2-6 
definition of 2-6 
determining 2-6 
library 
QUSRSYS library 13-4 
QUSRTOOL 
definition 1-5 
display examples 21-1 
panel groups, using word processing functions 
when creating 18-2 
limitations 
panel formatter 17-24 
line 
clearing a specified number of 3-13 
rolling data between 3-16 
line, instruction 
See instruction line 
line, options 21-23 
LINES (unformatted lines) tag 
example, unformatted lines A-77 
overview A-77 
use in help module 20-6 
LINK (hypertext link) tag 
conditional expressions 
CHKOBg built-in function A-79 
CHKUSRCLS (check user class) built-in 
function A-80 
example, hypertext link A-80 
overview A-78 
placement in UIM source 20-15 
UIM source showing panel groups using 20-15 
list 
adding entries, 17-9 
displaying 17-8 
incomplete processing 17-9 
initializing 17-8 
inserting entry from 17-10 
key A-76 
managing 17-7 
ordered A-118 
parameter A-129 
part A-107 


list (continued) 
removing entry from 17-10 
simple A-152 
unordered A-164 
updating 17-9 
LIST (list area) tag 
example 
dynamic list column heading formatting A-88 
list area A-86 
list area with list group columns A-87 
list area with three layout columns A-87 
overview A-82 
print formatting considerations A-86 
tags allowed table A-83 
list action (LISTACT) tag 
example, list actions A-95 
overview A-90 
recommended conventions A-94 
required conventions A-94 
list area 
example 
with list group columns A-87 
with three layout columns A-87 
help 19-3 
printed A-86 
scrolling 17-15 
list area (LIST) tag 
example 
dynamic list column heading formatting A-88 
list area A-86 
list area with list group columns A-87 
list area with three layout columns A-87 
overview A-82 
print formatting considerations A-86 
tags allowed table A-83 
list area scrolling 17-15 
list column (LISTCOL) tag 
formatting considerations A-99 
overview A-96 
list column group (LISTGRP) tag 
overview A-103 
list defining in UIM 
list definition (LISTDEF) tag 
emphasis values table A-101 
overview A-100 
list display 
changing list control field 21-28 
column headings 21-24 
description 21-21 
error condition rules 21-32 
example 
CUA 21-55 
extended action entry area 21-21 
extended action entry area 21-24 
format in an empty situation 21-33 
instruction line 21-22 


list display (continued) 


list entries on 17-10 
list fields 21-24 
list format, empty list 21-33 
list one selection item 21-33 
online help information 
DDS considerations 21-49 
description 21-48 
help areas for 21-48 
types 21-48 
operating 
extended action entry area 21-28 
guidelines 21-26 
list control field 21-26 
lists when options are specified 21-29 
options line 21-23 
paging location information 21-25 
positioning 
lists 21-26 
lowercase names ina list 21-27 
rules for cursor 21-31 
prompt areas 21-22 
response time for 17-11 
rules, error condition 21-32 
titles 21-22 


list entries on a list display 17-10 
list entry handle 17-9 

list entry pointer 17-10 

list fields on list displays 21-24 
list panel 


application programming 16-25 
creating 16-13 
source 16-17 


list part (LP) tag 


example, list part A-107 
overview A-107 
use in help module 20-5 


list view (LISTVIEW) tag 


layout and positions summary table A-105, A-106 
overview A-105 


LISTACT (list action) tag 


example, list actions A-95 
overview A-90 

recommended conventions A-94 
required conventions A-94 


LISTCOL (list column) tag 


formatting considerations A-99 
overview A-96 


LISTDEF (list definition) tag 


emphasis values table A-101 
overview A-100 


LISTGRP (list column group) tag 


overview A-103 


LISTVIEW (list view) tag 


layout and positions summary table A-105, A-106 
overview A-105 
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literal, graphic A-6 
location information, displays 21-19 
location of window 5-4, 5-5 
LOCK (Lock) keyword 3-42 
locked display file 3-1 
locking keyboard and positioning cursor 3-41 
LP (list part) tag 
example, list part A-107 
overview A-107 
use in help module 20-5 


Main Menu display 9-2 
major/minor return code 
major return code definitions 
00 8-11 
02 8-11 
03 8-11 
04 8-11 
08 8-11 
11 8-11 
34 8-11 
80 8-11 
81 8-11 
82 8-11 
83 8-11 
recovering from errors 
completion with exceptions 8-12 
device or session error on open or acquire opera- 
tion 8-14 
normal completion 8-11 
permanent device or session error on I/O opera- 
tion 8-13 
permanent system or file errors 8-13 
recoverable device or session errors on I/O oper- 


ation 8-14 
understanding 8-10 
managing 


panel functions 17-13 
managing list 17-7 
managing panel functions 17-13 
markup separator A-1 
MBAR (menu bar) tag 

example, menu bar A-108 

overview A-108 

tags allowed table A-108 
MBARC (menu bar choice) tag 

overview A-110 

tags allowed table A-110 
MDT (modified data tag) 

character translation 13-2 

definition 2-10 

resetting 3-23 

with ASSUME keyword 11-1 
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MDTOFF (Modified Data Tag Off) keyword 3-23 
member 


source 
definition 1-2 
MENU (menu area) tag 
example 


menu area with groups A-112 
simple menu area A-112 
tags allowed table A-111 
menu area 
help 19-6 
scrolling 17-16 
with groups 
example A-112 
menu area (MENU) tag 
example 
menu area with groups A-112 
simple menu area A-112 
tags allowed table A-111 


menu bar 
area help 19-13 
creating 6-7 
definition 6-7 


example 6-7, 6-62 
interaction with application 6-50 
interaction with pull-down menu 6-60 
using 17-27 
menu bar (MBAR) tag 
example, menu bar A-108 
overview A-108 
tags allowed table A-108 
menu bar choice (MBARC) tag 
overview A-110 
tags allowed table A-110 
Menu Bar Cursor Action (ACTIONS) dialog 
command B-4 
menu bar panel 
application programming 16-63 
creating 16-50 
source 16-53 
menu definition 16-2 
MENU dialog command B-10 
menu display 
See also application display 
Cancel key, using on 9-2 
changing attributes 9-16 
choosing which to display at sign-on time 9-3 
creating UIM 16-6 
CUA 21-52 
deleting 9-17 
description 21-8 
determining the previous menu 9-1 
display file 
building 9-7 
creating for 9-9 
creating menu object for 9-9 
creating message file for 9-9 


menu display (continued) 


display file (continued) 
DDS considerations 9-4 
DDS, specifying 9-7 
defining 9-4 
definition 9-1 
help for 9-4 
menu and help information, describing 9-7 
message file, adding messages to 9-9 
message file, describing menu actions in 9-5 
naming help formats for 9-6 


parts of 9-4 
displaying attributes 9-16 
example 


display file menu 9-8 
message file, adding messages to 9-9 
message file, describing menu actions in 9-6 
naming help formats in message file 9-6 
program menu 9-11 
program menu, CL source for 9-12 
RTNPNT(*NO) for program menu, CL source 
for 9-14 
sample single-choice 21-8 
using options and GO command 9-2 
Exit key, using on 9-2 
function key area 21-8 
identifier fields 21-34 
initial 9-3 
instruction line 21-9 
menu displays, single-choice 21-9, 21-10 
menu selection entry field 21-10 
menu stack 9-1 
naming conflicts, avoiding 
changing command default after command dupli- 
cation 9-16 
generic menu specifications 9-16 
naming, deciding how to 9-15 
placement in library list 9-16 
specifying library 9-16 
ways 9-15 
online help information 
DDS considerations 21-45 
description 21-44 
help areas for 21-44 
types 21-44 
operating guidelines 21-10 
optional 21-34 
options 21-9 
program 
building 9-11 
creating CL program for 9-12 
creating display file 9-12 
creating menu for 9-13 
defining 9-10 
definition 9-1 
describing 9-11 
entering CL source for 9-12 


menu display (continued) 
program (continued) 


exiting without returning to previous menu 9-13 


passing parameters for 9-10 
returning to after running the GO command 9-1 
selection entry field 21-10 
system, running 9-1 
user interface manager (UIM) 16-6 
user-defined 

running 9-1 

types 9-1 

menu group (MENUGRP) tag 
tags allowed table A-114 
menu group (MNUGRP) tag 
overview A-114 
menu item (MENUI or Ml) tag 
overview A-115 
MENU object type 9-1 
menu object, defining 
*DSPF menu 9-7 
*“UIM menu 16-6 
menu-bar choice 
defining 6-7 
translation of 6-9 
menu-bar choice help 
example 6-57 
Menu-Bar Display (MNUBARDSP) keyword 
application record 6-50, 6-62 
menu-bar record 6-51, 6-65 
menu-bar help list 
example 6-59 
menu-bar record 
MNUBARDSP_ 6-65 
menu-bar separator 
creating 6-7 
defining 6-8 
definition 6-7 
suppressing 6-8 
menu-bar switch key 
defining 6-22 
definition 6-22 
MENUGRP (menu group) tag 
overview A-114 
tags allowed table A-114 
MENUI or MI (menu item) tag 
overview A-115 
message 
automatically handling error 8-7 
available functions for display files 8-1 
CPF4001-40FF 8-10 
CPF4101-43FF 8-10 
CPF4401-44FF 8-10 
CPF4501-46FF 8-10 
CPF4701-48FF 8-10 
CPF4901-49FF 8-10 
CPF5001-50FF 8-10 
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message (continued) 
CPF5101-53FF 8-10 
CPF5501-56FF 8-10 
creating and displaying 8-1 
description 21-49 
displaying 
in field 8-3 
in program message queue 8-4 
message line for 8-3 
on message line 8-2 
on message line when subfile control record 
written 8-2 
priorities for 8-3 
through subfile 8-4 
error 
displaying from subfiles 4-23 
examples 
ERRSFL keyword 8-4 
SFLMSGID keyword 8-5 
guidelines 21-49 
line relationship, CUA 21-52 
reasons for 8-1 
sounding alarm for 8-7 


system 
alert 8-9 
analyzing 8-8 


detecting 8-8 
diagnostic 8-8 
escape 8-8 
file status code 8-8 
message queues 8-8 
notifying 8-8 
permanent 8-9 
reporting 8-8 
status 8-8 
System/36 application compatibility G-4 
understanding 8-9 
window 5-6 
Message Alarm (MSGALARM) keyword 8-7 
message description 2-16 
message field to display message on message 
line 8-3 
message file 
adding messages to 9-9 
creating 9-9 
describing menu action in 9-5 
message line 
definition 2-10 
scrolling 17-15 
use 2-10 
Message Location (MSGLOC) keyword 5-6 
message subfile 4-23 
message text symbol A-5 
message, monitor 
See message 
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messages displayed on message line priorities 8-3 
mixed display 
example 21-21 
mnemonic 
coding, not valid 6-38 
defining 6-38 
definition 6-1 
valid coding for 6-38 
MNUBARDSP (Menu-Bar Display) keyword 
application record 6-50, 6-62 
menu-bar record 6-51, 6-65 
mode, display 
changing 4-17 
definition 4-17 
displaying subfiles horizontally with 4-17 
modified data tag (MDT) 
character translation 13-2 
definition 2-10 
resetting 3-23 
with ASSUME keyword 11-1 
Modified Data Tag Off (MDTOFF) keyword 3-23 
monitor message 8-9 
MOREKEYS (Display More Function Keys) dialog 
command B-10 
MOUBTN (Programmable Mouse Button) 
keyword 6-69 
mouse button, programmable 
See Programmable Mouse Button (MOUBTN) 
keyword 
Move Object (MOVOBJ) command D-15 
Move to Top (MOVETOP) dialog command _ B-11 
MOVETOP (Move to Top) dialog command _ B-11 
moving 
cursor 
CSRINPONLY keyword 2-16 
using cursor keys 6-62 
using tab key 6-61 
window 5-11 
MOVOBJ (Move Object) command D-15 
MSG (Display Message) dialog command B-11 
MSGALARM (Message Alarm) keyword 8-7 
MSGID (Message Identifier) keyword 8-3 
MSGLOC (Message Location) keyword 5-6 
multiple panel foldup when EXIT requested 17-24 
multiple-choice selection field 
colors and display attributes 6-40 
definition 6-10 
vertical 6-14 
multiple-choice selection list 
creating 6-26 
definition 6-24 
example 6-25 
multiple-selection field (UIM) 
example A-53 


N 


name syntax 
alphabetic conversion A-4 
object name 
restrictions A-4 
on HELP tag 
restrictions A-4 
national language considerations and DBCS 20-12 
national language translation 
sentence-ending characters A-2 
negative numeric input data, handling 3-40 
nesting 
imbeds 
source files A-6 
No CCSID (NOCCSID) keyword 13-3 
NOCCSID (No CCSID) keyword 13-3 
node (hypertext), definition 
See online help information, hypertext 
NOTE (note) tag 
use in help module 20-4 
note (NT or NOTE) tag 
overview A-117 
note (NT) tag 
example, using a note A-117 
tags allowed table A-117 
use in help module 20-4 
NT (note) tag 
example, using a note A-117 
tags allowed table A-117 
use in help module 20-4 
NT or NOTE (note) tag 
overview A-117 
numeric input data, handling negative 3-40 
numeric value 
display form A-24 
binary A-24 
example values table A-24 


O 


object 
creating 16-3 
definition 2-1 


enhancements to object management D-15 
panel group A-3 
object name 
name syntax A-4 
restrictions A-4 
ODP (open data path) 
definition 3-50 
for improving system performance 14-2 
sharing for same job 14-2 
office document 
See document, office 


OfficeVision/400* document 
See document, office 
OL (ordered list) tag 
example, ordered list A-119 
overview A-118 
tags allowed table A-118 
use in help module 20-5 
online help information 
adding to adisplay 18-1 
contextual help 18-3 
creating a sample display with 1-1 
description 21-44 
documents, office 
comparing with panel groups and records 18-2 
creating for help 20-18 
help, defining for 20-18 
help, specifying for 18-9 
HLPDOC keyword 18-10 
HLPDOC keyword with option indicators 18-11 
option indicators, specifying with 18-11 
panel groups and records in same file, 
with 18-11 
viewing without Help key 20-19 
enabling Help key 18-2 
entry displays 
DDS considerations 21-46 
description 21-46 
help areas for 21-46 
types 21-46 
example 
building with display file 1-1 
command help 20-16 
display showing help areas 18-4 
HLPCMDKEY keyword 18-20 
HLPCMDKEY keyword with response 
indicators 18-21 
HLPDOC keyword 18-10 
HLPDOC keyword with option indicators 18-11 
HLPPNLGRP keyword 18-7 
HLPPNLGRP keyword with option 
indicators 18-8 
HLPRCD keyword 18-13 
HLPRCD keyword with option indicators 18-14 
imbedded help modules in panel group 20-2 
imported help modules 20-3 
ISCH tag 20-9 
ISCHSYN tag 20-9 
LINK tag 20-15 
panel groups with help modules 20-2 
secondary help 18-18 
exiting, System/36 application compatibility G-8 
extended help 18-3 
H specifications 
definition 18-4 
entering in DDS source 18-4 
order in DDS source 18-4 
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help areas 
DDS keywords for 18-4 
defining 18-3 
office documents, specifying for 18-9 
panel groups, specifying 18-6 
record 18-4 
records, specifying for 18-12 
required DDS source 18-4 
Help key 
enabling 18-2 


returning control to program after pressing 18-20 


returning control to program without 
pressing 18-22 
help text displayed according to cursor 
position 17-17 
hypertext 
creating links 20-14 
definition 20-13 
designing links 20-14 
reference phrase, definition 20-14 
index search 
accessing 19-4 
index search function 
See also InfoSeeker function 
deciding topics 20-9 
function 20-6 
root words, choosing for topic 20-10 
root words, defining 20-9 
root words, including as synonyms 20-9 
synonyms for root words, designating 20-9 
synonyms, choosing for topic 20-10 
topics, defining 20-9 
UIM tags for 20-6 
information display 
DDS considerations 21-47 
description 21-47 
help areas for 21-47 
InfoSeeker 
accessing 19-3 
list display 
DDS considerations 21-49 
description 21-48 
help areas for 21-48 
menu display 
DDS considerations 21-45 
help areas for 21-44 
types 21-44 
overview 19-2 
panel groups 
adding entries to search index 20-17 
command help, assigning 20-16 
comparing with documents and records 18-2 
creating 20-15 
creating hypertext links 20-14 
creating search index 20-16 
DDS functions for 18-6 
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online help information (continued) 
panel groups (continued) 


deleting 20-15 

deleting search index 20-17 

designing hypertext links 20-14 

documents and records in same file with 18-8 

emphasizing and formatting text in help 
modules 20-4 

entering UIM source for 20-1 

full-screen help, indicating 18-6 

headings in help modules, adding 20-4 

help modules, linking 20-13 

help modules, using more than once 20-2 

help, specifying for 18-6 

highlighting text in help modules 20-4 

HLPPNLGRP keyword 18-7 

HLPPNLGRP keyword with option 
indicators 18-8 

hypertext 20-13 

hypertext reference phrase 20-14 

index search function 20-6 

Index search, enabling 18-6, 19-4 

InfoSeeker, enabling 18-6, 19-3 

making lists in help modules 20-5 

name of help screen, defining 18-6 

option indicators, specifying with 18-8 

organizing with help modules 20-2 

paragraphs and notes, defining in help 
modules 20-4 

programming keywords and variables, identifying 
in help modules 20-5 

purpose of UIMtags 20-1 

records and documents in same file with 18-8 

removing entries from search index 20-17 

root words, choosing for index search 
topic 20-10 

root words, defining 20-9 

root words, including as index search 
synonyms 20-9 

secondary help, excluding as_ 18-6 

structured text in help modules, indicating 20-6 

synonyms for root words, designating 20-9 

synonyms, choosing for index search 
topic 20-10 

topics, defining 20-9 

user-defined, enabling 19-4 

uses for 20-1 

using a help module contained in different 20-3 


record, DDS 


comparing with panel groups and 
documents 18-2 

entering source 18-14 

help boundaries 18-17 

help group 18-17 

help list 18-16 

help sublist 18-17 

help, defining for 20-19 


online help information (continued) 
record, DDS (continued) 
help, specifying for 18-12 
HLPCMDKEY keyword 18-20 
HLPCMDKEY keyword with response 
indicators 18-21 
HLPRCD keyword 18-13 
HLPRCD keyword with option indicators 18-14 
option indicators, specifying with 18-13 
paging between help displays 18-16 
paging through H specifications 18-16 
primary help 18-16 
restrictions on 18-15 
restrictions on secondary help 18-19 
secondary help 18-16, 18-18 
secondary help, displaying 18-17 
secondary, determining the sequence of 18-18 
with documents in same file 18-15 
with panel groups in same file 18-12 
returning control to program after pressing Help 
key 18-20 
returning control to program without pressing Help 
key 18-22 
user-defined panel group 
accessing 19-4 
open data path (ODP) 
definition 3-50 
for improving system performance 14-2 
sharing for same job 14-2 
open feedback area 
contents 3-3 
definition 3-3 
device definition list C-4 
individual descriptions C-1 
Open operation 
definition 3-2 
file resource allocation for 3-1 
files shared in job 3-51 
ILE C function for 3-49 
ILE COBOL statement for 3-49 
ILE RPG operation for 3-49 
obtaining information about 3-3 
opening 
UIM application 17-1 
operating guideline 
entry displays 21-17 
information displays 21-21 
list display 
See list display 
menu displays, single choice 21-10 
operator 
conditional A-27 
relational A-11 
option indicator 
example 
HLPDOC keyword with option indicators 18-11 
HLPPNLGRP keyword with option 
indicators 18-8 


option indicator (continued) 
example (continued) 
HLPRCD keyword with option indicators 18-14 
MNUBARCHC (Menu Bar Choice) keyword 6-9 
secondary help 18-18 
office documents, defining for help with 18-11 
panel groups, defining with 18-8 
records, defining with 18-13 
removing from record area 2-15 
option line (OPTLINE) tag 
overview A-120 
options line, list displays 21-23 
OPTLINE (option line) tag 
overview A-120 
ordered list (OL) tag 
example, ordered list A-119 
overview A-118 
tags allowed table A-118 
use in help module 20-5 
organization 
panel outline A-4 
UIM menu outline A-4 
outline, panel 
organization A-4 
UIM menu outline A-4 
outline, UIM menu 
organization A-4 
output data 
writing and reading input at same time 3-40 
writing to display 3-5 
output field 
definition 2-9 
editing 2-23 
examples 
displayed in response to request, display with 
input and 2-10 
using 2-9 
output file 
defining 2-28 
output operation 
effect of OVERLAY and ERASE on 3-10 
positioning cursor after 3-28 
returning cursor position to application 3-29 
output-only file, defining 2-28 
output/input field 
definition 2-9 
erasing 3-23 
using 2-9 
OVERLAY (Overlay) keyword 
description 3-10 
effect on help-list updating 18-16 
erasing records 3-10 
example 
differences between CLRL and 3-15 
examples 
with ERASE keyword 3-10 
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OVERLAY (Overlay) keyword (continued) 
system performance considerations 14-3 
System/36 application compatibility G-2 

override 
applying when compiling program 7-4 
attributes 3-18 
CL programs 

included in 7-1 
QCMDEXC, use of 7-1 
commands that ignore or restrict 7-9 
Delete Override (DLTOVR) command 7-5 
deleting 7-5 
determining whether or not to use 7-1 
different file types 7-6 
display file attributes in HLL programs 7-1 
display file names and attributes in HLL 
programs 7-3 
display file names in HLL programs 7-3 
Display Override (DSPOVR) command 7-6 
displaying 7-6 
effect on other jobs 7-1 
entering 7-1 
examples 
applying when compiling program 7-5 
attribute of display file 7-1 
different display file 7-3 
different display file and attributes 7-4 
file redirection 
definition 7-6 
different file types 7-6 
level checking (LVLCHK) 7-6 
same file types 7-6 
table of defaults for combinations 7-7 
valid for input and output 7-7 
Override with Display File (OVRDSPF) command 
file attributes 7-1 
file names 7-3 
file names and attributes 7-3 
performance considerations 14-2 
properties of 7-1 
same file types 7-6 
when in effect 7-1 
when to apply 7-1 

Override Attribute (OVRATR) keyword 
system performance considerations 14-2 
use 3-18 

Override Data (OVRDTA) keyword 
description 3-20 
system performance considerations 14-2 

Override with Display File (OVRDSPF) command 
compared to CHGDSPF 2-2 
file attributes 7-1 
file names 7-3 
file names and attributes 7-3 

Override with Printer File (OVRPRTF) 

command D-5 
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overriding and sharing printer file 17-37 
OVRATR (Override Attribute) keyword 
system performance considerations 14-2 
use 3-18 
OVRDSPF (Override with Display File) command 
compared to CHGDSPF 2-2 
file attributes 7-1 
file names 7-3 
file names and attributes 7-3 
indicating DBCS files D-5 
OVRDTA (Override Data) keyword 
description 3-20 
system performance considerations 14-2 
OVRPRTF (Override with Printer File) 
command D-5 


p 


P (paragraph) tag 

example, paragraph tag A-121 

overview A-121 

placement in UIM source 20-2 

use in help module 20-4 
page 420 for code page conversion A-20 
page 424 for code page conversion A-20 
Page Down (PAGEDOWN) keyword 

for function key 2-12 

specifying alternative 2-13 
page eject during printing 17-37 
Page Up (PAGEUP) keyword 

for function key 2-12 

specifying alternative 2-13 
page, code 

See code page 
PAGEDOWN (Page Down) keyword 

for function key 2-12 

specifying alternative 2-13 
PAGEDOWN dialog command B-11 
PAGEUP (Page Up) keyword 

for function key 2-12 

specifying alternative 2-13 
PAGEUP dialog command B-12 
paging 

help displays, DDS records 18-16 

location information, list displays 21-25 
panel 

areas A-2 

definition 16-2, A-2 

group object A-2 

help A-2 

organization A-2 

outline A-2 

UIM menu outline A-2 
PANEL (display panel) tag 

example, panel definition A-127 

overview A-122 


PANEL (display panel) tag (continued) 
tags allowed table A-122 
panel contents definition 17-22 
panel formatter limitations 17-24 
panel formatting 
application control 17-23 
concepts 17-22 
definition 17-22 
panel group 
See also tag, UIM 
accessing index search 19-4 
accessing user-defined 19-4 


adding UIM tags for index search function 20-6 


command help, assigning 20-16 
comparing with documents and records 18-2 
creating 20-15 
definition 1-1, 16-2 
deleting 20-15 
entering UIM source for 20-1 
examples 
command help 20-16 
help modules 20-2 
HLPPNLGRP keyword 18-7 
HLPPNLGRP keyword with option 
indicators 18-8 
imbedded help modules 20-2 
imported help modules 20-3 
ISCH tag 20-9 
ISCHSYN tag 20-9 
LINK tag 20-15 
heading, adding in help modules 20-4 
help modules 
emphasizing and formatting text 20-4 
highlighting text 20-4 
hypertext 20-13 
linking 20-13 
using more than once 20-2 
using ones contained in different panel 
group 20-3 
help, specifying for 18-6 
hypertext, definition 20-13 
index search function 
function 20-6 
root words, choosing for topic 20-10 
root words, including as synonyms 20-9 


synonyms for root words, designating 20-9 


synonyms, choosing for topic 20-10 
topics, deciding 20-9 
InfoSeeker, accessing 19-3 
making lists in help modules 20-5 
organizing with help modules 20-2 
paragraphs and notes, defining in help 
modules 20-4 
programming keywords and variables, 
identifying 20-5 
search index 
adding entries to 20-17 


panel group (continued) 
search index (continued) 
creating 20-16 
deleting 20-17 


removing entries from a search index 20-17 
structured text in help modules, indicating 20-6 


topics, defining 20-9 
uses for 20-1 
panel group (PNLGRP) tag 
overview A-139 
placement in UIM source 20-2 
tags allowed table A-139 
panel group definition language 
imbedding source files A-6 
markup/content separator A-1 
national language translation 
sentence-ending characters A-2 
overview A-2 
panel group element 16-3 
panel group object 
creating 16-13 
definition A-3 
panel list foldup 17-26 
panel markup tag 
See also tag 
definition 20-4 
paragraph (P) tag 
example, paragraph tag A-121 
overview A-121 
placement in UIM source 20-2 
use in help module 20-4 
paragraph continuation (PC) tag 
example, paragraph continuation A-131 
overview A-131 
use in help module 20-4 
parameter 
data queue (DTAQ) 12-1 
DTAQ (data queue) 12-1 
passed for program menus 9-10 
restore display (RSTDSP) 
example 3-43 
return point (RTNPNT) parameter 
for display file menus 9-1 
for program menus 9-1 
RSTDSP (restore display) 
example 3-43 
RTNPNT (return point) parameter 
for display file menus 9-1 
for program menus 9-1, 9-13 
SHARE (share) 14-2 
parameter list (PARML) tag 
example, parameter list A-130 
overview A-129 
tags allowed table A-129 
use in help module 20-5 


Index 
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PARML (parameter list) tag 
example, parameter list A-130 
overview A-129 
tags allowed table A-129 
use in help module 20-5 
Passed Record (PASSRCD) keyword 11-3 
passing data 
between routing steps 11-3 
in the same routing step 11-1 
PASSRCD (Passed Record) keyword 
example DDS source 11-3 
use 11-3 
PC (paragraph continuation) tag 
example, paragraph continuation A-131 
overview A-131 
use in help module 20-4 
PDACCEL (pull-down accelerator) tag 
overview A-132 
PDFLD (pull-down field) tag 
overview A-133 
tags allowed table A-133 
PDFLDC (pull-down field choice) tag 
overview A-134 
recommended conventions A-136 
required conventions A-136 
PDM (programming development manager) 
definition 1-2 
performance 
command attention keys versus command function 
keys 14-3 
DDS windows 14-4 
deferring write operation 14-1 
designating primary screen size 14-1 
ERASEINP keyword, considerations with 14-3 
invite operation 14-3 
INZINP keyword, considerations with 14-3 
overlapping but not deleting records 14-2 
OVERLAY keyword, considerations with 14-3 
override commands 14-2 


PUTOVR, OVRDTA and OVRATR keywords, consid- 


erations with 14-2 
restoring display 14-3 
RSTDSP (restore display) 
keywords that require 14-3 
system performance considerations 14-3 
sending records with input fields 14-2 
sharing open data paths for same job 14-2 
subfile use 14-1 
ways to improve using displays 14-1 
window application 5-13 
period (.) symbol A-5 
PK (programming keyword) tag 
overview A-138 
use in help module 20-5 
placement of window 5-4, 5-5 
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PNLGRP (panel group) tag 
overview A-139 
placement in UIM source 20-2 
tags allowed table A-139 
UIM source showing panel groups with help 
modules 20-2 
pointer device event 
processing priority 
other pointer device 6-79 
shifted left button pressed 6-76 
shifted left button released 6-76 
shifted right button pressed 6-78 
unshifted left button double click 6-75 
unshifted left button pressed 6-73 
unshifted left button released 6-75 
processing states 6-72 
programmable mouse button 6-69 
pop-up window 
adding 17-31 
adding over another panel 17-27 
adding to display stack 17-31 
help information A-61 
removing 17-31 
pop-up window and pull-down menu 
differences 17-28 
position of window 5-4, 5-5 
possible choices information, entry displays 21-16 
primary help, definition 18-16 
PRINT (Print Display) dialog command B-12 
PRINT (Print) keyword 
enabling 2-25 
for function key 2-12 
results available (table) 2-25 
Print Display (PRINT) dialog command B-12 
print head panel (PRTHEAD) tag 
example, print title lines A-145 
layout of title lines tables A-144, A-145 
overview A-142 
tags allowed table A-142 
print head panel printing 17-35 
Print key 
enabling 2-25 
results available (table) 2-25 
print panel (PRTPNL) tag 
overview A-146 
tags allowed table A-146 
print panel printing 17-35 
print title lines 
example A-145 
print trailer message (PRTTRAIL) tag 
example, trailer message A-148 
overview A-148 
printer characters, incorrect 17-4 
printer file sharing and overriding 17-37 
printer files in DBCS D-5 


PRINTER parameter 2-26 
printing 
concepts 17-33 
DBCS conversion dictionary D-19 
display 2-25 
double-byte character set (DBCS) 
considerations 17-37 
information area A-69 
introduction 17-33 
list area A-86 
page eject 17-37 
print head panel 17-35 
print panel 17-35 
trailer 17-36 
priorities for displaying messages on message 
line 8-3 
problem analysis 
damaged DBCS devices D-10 
Problem Handling menu 9-2 
productivity gains with UIM 15-1 
productivity improvements with UIM 15-1 
program menu 
See also menu display 
definition 9-1 
return code values, table of 9-10 
program-described data 
definition 2-3 
description 2-4 
example for assigning display space 2-27 
program versus system view 2-4 
using 2-27 
program-to-system field 
understanding how to use 2-10 
with DSPATR keyword 2-21 
program, CL 
See CL programs 
program, IBM-supplied 
QRCVDTAQ (receive data queue) 12-1 
QSNDDTAQ (send data queue) 12-1 
Programmable Mouse Button (MOUBTN) keyword 
AID codes to be returned 6-70 
benefits 6-70 
event processing priority 
other pointer device 6-79 
shifted left button pressed 6-76 
shifted left button released 6-76 
shifted right button pressed 6-78 
unshifted left button double click 6-75 
unshifted left button pressed 6-73 
unshifted left button released 6-75 
event processing states 6-72 
NWS considerations 6-72 
operation 6-71 
overview 6-69 
pointer device event 6-69 


programming development manager (PDM) 
definition 1-2 
programming example 
window use 5-15 
programming keyword (PK) tag 
overview A-138 
use in help module 20-5 
Programming menu 9-2 
programming variable (PV) tag 
overview A-149 
use in help module 20-5 
prolog area 
defining 17-36 
prolog section 
panel group A-4 
prompt area 
entry displays 21-12 
list display 21-22 
PROMPT dialog command B-13 
prompt, field 
See field prompts 
prompting 
action list option B-13 
command B-13 
entry field B-13 
protecting entry field 2-19 
PRTHEAD (print head panel) tag 
example, print title lines A-145 
layout of title lines tables A-144, A-145 
overview A-142 
tags allowed table A-142 
PRTPNL (print panel) tag 
overview A-146 
tags allowed table A-146 
PRTTRAIL (print trailer message) tag 
example, trailer message A-148 
overview A-148 


PSHBTNCHC (Push Button Choice) keyword 6-35 
PSHBTNEFLD (Push Button Field) keyword 6-35 


pull-down accelerator (PDACCEL) tag 
overview A-132 
pull-down field (PDFLD) tag 
overview A-133 
tags allowed table A-133 
pull-down field choice (PDFLDC) tag 
overview A-134 
recommended conventions A-136 
required conventions A-136 
pull-down menu 
CHECK(FE) keyword 6-18 
creating 6-18 
definition 6-7 
example 6-18, 6-62 
interaction with menu bar 6-60 
receiving input 6-53 
removing after receiving input 6-55 
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pull-down menu (continued) 
restrict cursor 6-24 
single-choice selection field 6-18 
updating before displaying 6-55 
pull-down menu and pop-up window 
differences 17-28 
PULLDOWN dialog command B-14 
PULLINPUT (Pull-Down Menu Input) parameter 
example 6-54 
push button 
creating 6-35 
definition 6-34 
example, DDS 6-35 
Push Button Choice (PSHBTNCHC) keyword 6-35 
Push Button Field (PSHBTNFLD) keyword 6-35 
Put with Explicit Override (PUTOVR) keyword 
for repeatedly entered data 3-21 
more efficient coding 3-20 
sample DDS source 3-18 
put-relative operation for subfiles 
BASIC statement for 4-15 
definition 4-12 
ILE C function for 4-15 
ILE COBOL statement for 4-15 
ILE RPG operation for 4-15 
Put-Retain (PUTRETAIN) keyword 
example 
field level 3-24 
record level 3-24 
restriction with USRDSPMGT keyword G-10 
System/36 application compatibility G-2 
using 3-23 
PUTOVR (Put with Explicit Override) keyword 
description 3-18 
example 
more efficient coding 3-20 
repeatedly entered data 3-21 
sample DDS source 3-18 
system performance considerations 14-2 
System/36 application compatibility G-6 
PUTRETAIN (Put-Retain) keyword 
example 
field level 3-24 
record level 3-24 
restriction with USRDSPMGT keyword G-10 
System/36 application compatibility G-2 
using 3-23 
PV (programming variable) tag 
overview A-149 
use in help module 20-5 
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QIGC system value 
DBCS conversion dictionaries 

creating D-15 

deleting D-19 
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QIGC system value (continued) 
DBCS conversion dictionaries (continued) 
display D-19 
edit, examples of D-17 
editing (adding and changing terms) D-16 
perform object management functions with D-15 
printing D-19 
QIGC2424 (DBCS font table) D-8 
QRCVDTAQ (receive data queue) program 12-1 
QSNDDTAQ (send data queue) program 12-1 
QSYSIGCDCT (system-supplied DBCS conversion 
dictionary) 
contents D-14 
definition D-14 
queue, data 
See DTAQ (data queue) parameter 
QUSRIGCDCT (user-created dictionary) D-15 
QUSRSYS library 13-4 
QUSRTOOL library 
definition 1-5 
display examples 21-1 
panel groups, using word processing functions when 
creating 18-2 


R 


radio button 
definition 6-1 
example 6-1 
read operation 
canceling read operation, CL command for 3-49 
definition 3-33 
definition for subfile 4-15 
subfiles 
BASIC statement 4-15 
ILE C function for 4-15 
ILE COBOL statement for 4-15 
ILE RPG operation for 4-15 
with no wait 
CL command for 3-49 
ILE COBOL statement for 3-49 
ILE RPG operation for 3-49 
with wait 
CL command for 3-49 
ILE C function for 3-49 
ILE COBOL statement for 3-49 
ILE RPG operation for 3-49 
read-from-invited-program-devices operation 
after inviting input 3-30 
from CL programs, 
reading-from-invited-devices 3-33 
ILE C function for 3-49 
ILE COBOL statement for 3-49 
ILE RPG operation for 3-49 
understanding 3-32 


reading 
data from window 5-10 
receiving 
data 3-4 
receiving input 
from pull-down menu 6-53 
using PULLINPUT 6-53 
recommended convention 
list action (LISTACT) tag A-94 
pull-down field choice (PDFLDC) tag A-136 
record area, removing option and response indica- 
tors from 2-15 
record format 
changing on display 3-8 
checking for changes to 2-7 
contents 2-7 
defining display fields and functions in 2-7 
definition 1-1 
description 2-7 
determining active 3-5 
field, how to use 2-9 
maximum number for display file 2-15 
maximum number of fields in 2-10 
order written to display 3-9 
output and input, for 3-5 
overlaying and erasing on display 3-10 
replacing 3-9 
replacing on display 3-8 
starting on specific line 3-11 
viewing on display 2-8 
record format table, active 3-5 
record-level description 
definition 2-3 
with field-level descriptions 2-3 
with no field-level descriptions 2-3 
record, DDS 
comparing with panel groups and documents 18-2 
containing input fields, improving performance 
with 14-2 
definition 2-3 
definition for help 1-6 
displaying secondary help 18-17 
displaying two or more 3-10 
entering for help 18-14 
erasing from display during overlay 3-10 
examples 
HLPCMDKEY keyword 18-20 
HLPCMDKEY keyword with response 
indicators 18-21 
HLPRCD keyword 18-13 
HLPRCD keyword with option indicators 18-14 
secondary help 18-18 
help 
defining for 20-19 
specifying for 18-12 
improving performance when sending 14-2 


record, DDS (continued) 
initializing (diagram) 3-36 
keeping on display 3-23 
mode to display 3-27 
not occupying space on display 3-8 
overlapping but not deleting to improve system 
formance 14-2 
paging between display 18-16 
placing on display 3-5 
resetting modified data tags for 3-23 
restrictions on 18-15 
restrictions on secondary help 18-19 
retrieving with WAIT command 3-33 
rules for displaying on more than one line 3-5 


per- 


secondary help, determining sequence of 18-18 


use by I/O statements 3-4 
valid placement of, figure 3-6 
recovering from errors 8-11 
reference field 
definition 2-11 
relational operator A-11 
release operation 
definition 3-49 
ILE C function for 3-49 
ILE COBOL statement for 3-49 
ILE RPG operation for 3-49 
Remove Search Index Entry (RMVSCHIDXE) 
command 20-17 
Remove Window (RMVWDW) keyword 5-12 
removing 
entry from list 17-10 
pop-up window 17-30 
pop-windows using APIs_ 17-30 
pull-down menu 6-55 
window 5-12, 17-30 
removing access 
F18=More indexes 19-5 
Rename Object (RNMOBJ) command D-15 
request processor program when displaying 
panel 17-33 
required convention 
list action (LISTACT) tag A-94 
pull-down field choice (PDFLDC) tag A-136 
resolving 
HTML field overlap 6-83 
resource allocation 
description 3-1 
effect on display station error handling 3-1 
understanding how system allocates 3-1 
response indicator 
CAnn key, use with 2-13 
CFnn key, use with 2-12 
definition 2-12 
enabling simultaneously 2-15 
function keys, use with 2-12 
HLPCMDKEY keyword, use with 18-21 
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response indicator (continued) 
removing from record area 2-15 
restriction with USRDSPMGT G-10 
ROLLDOWN keyword, use with 2-15 
ROLLUP keyword, use with 2-15 
SETOF or SETOFF keyword, use with 2-15 
response time 
for list displays 17-11 
list displays 17-11 
window application 5-13 
restore display (RSTDSP) parameter 
example 3-43 
keywords that require 14-3 
system performance considerations 14-3 
use 3-43 
Restore Library (RSTLIB) command D-15 
Restore Object (RSTOBJ) command 
DBCS conversion dictionaries D-15 
DBCS sort table D-12 
restoring DBCS font tables 
copying from tape or diskette (restoring) D-9 
copying onto diskette (saving) D-9 
restoring DBCS sort tables 
copying from file (move from System/36) D-13 
copying to file (move to System/36 or 
AS/Entry) D-12 
restrict cursor 
PULLDOWN keyword 6-24 
WINDOW keyword 5-5 
restrictions 
5250 engraved keys 17-14 
command line 17-19 
name syntax 
HELP tag A-4 
object names A-4 
on command line 17-19 
using dialog variables 17-3 
retain command and function keys 
System/36 application compatibility G-9 
Retain Command Keys (RETCMDKEY) keyword 
System/36 application compatibility G-10 
Retain Function Keys (RETKEY) keyword 
System/36 application compatibility G-10 
RETCMDKEY (Retain Command Keys) keyword 
System/36 application compatibility G-10 
RETKEY (Retain Function Keys) keyword 
System/36 application compatibility G-10 
RETRIEVE (Retrieve Command String) dialog 
command B-14 
Retrieve Command String (RETRIEVE) dialog 
command B-14 
RETURN (Return Control to Application) dialog 
command B-14 
return code 
binary program menus 9-10 
display file 
description E-1 
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return code (continued) 
display file (continued) 
major 00 E-1 
major 02. E-1 
major 03. E-2 
major 04 E-2 
major 08 and 11 E-3 
major 34 E-3 
major 80 E-3 
major 81 E-5 
major 82 E-6 
major 83 E-10 
major/minor 
See major/minor return code 
Return Control to Application (RETURN) dialog 
command B-14 
Return Cursor Location (RTNCSRLOC) 
keyword 3-29 
return point (RTNPNT) parameter 
for program menus 9-13 
return-field (RTNFLD) parameter 
description 6-55 
example 6-56 
returning cursor position within subfile to applica- 
tion 3-29 
returning mode of subfile to application 3-29 
returning to menu after running GO command 9-1 
reverse text (RT) tag 


example 
left-to-right formatting on a left-to-right 
panel A-150 


left-to-right formatting on right-to-left panel A-150 
overview A-150 
Revoke Object Authority (RVKOBJAUT) 
command D-15 
right slash (/) symbol A-5 
right-to-left cursor movement 2-16 
right-to-left display processing 2-19 
RMVSCHIDXE (Remove Search Index Eniry) 
command 20-17 
RMVWDW (Remove Window) keyword 5-12 
RNMOBJ (Rename Object) command D-15 
Roll Down (ROLLDOWN) keyword 
for function keys 2-12 
Roll Up (ROLLUP) keyword 
example with SFLSIZ and SFLPAG 4-19 
ROLLDOWN (Roll Down) keyword 
function keys 2-12 
response indicators for 2-15 
ROLLUP (Roll Up) keyword 
example with SFLSIZ and SFLPAG 4-19 
function keys 2-12 
improving subfile performance 14-1 
response indicators for 2-15 
root words for index search 
See online help information 


routing step 
passing data between programs insame_ 11-1 
passing data between steps 11-3 
RSTDSP (restore display) parameter 
example 3-43 
keywords that require 14-3 
system performance considerations 14-3 
use 3-43 
RSTLIB (Restore Library) command D-15 
RSTOBJ (Restore Object) command 
DBCS conversion dictionaries D-15 
DBCS sort table D-12 
RT (reverse text) tag 
example 
left-to-right formatting on left-to-right panel 
left-to-right formatting on right-to-left panel 
overview A-150 
RTNCSRLOC (Return Cursor Location) 
keyword 3-29 
RTNELD (return field) parameter 
description 6-55 
example 6-56 
rule 
edit description use F-5 
entry fields 21-15 
list display 
cursor positioning 21-31 
error conditions 21-32 
run-time errors, recovering from 3-52 
running 
system and user-defined menus 9-1 
RVKOBJAUT (Revoke Object Authority) 
command D-15 


S 


sample figure 
example A-59 

sample heading 
example A-170 

SAVCHGOB4J (Save Changed Object) 

command D-15 
Save Changed Object (SAVCHGOBJ) 
command D-15 

Save Library (SAVLIB) command D-15 

Save Object (SAVOBJ) command 
DBCS conversion dictionaries D-15 
DBCS sort table D-12 

Save System (SAVSYS) command 
DBCS conversion dictionaries D-15 
DBCS sort tables D-12 

saving 
DBCS sort tables D-12 

SAVLIB (Save Library) command D-15 

SAVOBJ (Save Object) command 
DBCS conversion dictionaries D-15 


SAVOBJ (Save Object) command (continued) 
DBCS sort table D-12 
SAVSYS (Save System) command 
DBCS conversion dictionaries D-15 
DBCS sort tables D-12 
screen design aid (SDA) 
compared to direct DDS source entry 2-5 
definition 1-5 
screen size 
alternate 3-27 
condition names 2-24 
examples 
DDS for subfiles for two 2-25 
DDS for two 2-24 
improving performance with 14-1 
primary and secondary 2-25 
valid 2-24 
scroll bar 
creating 6-31 
definition 6-24, 6-30 
example 6-25 
example, DDS 6-33 
operation 6-33 
sizing 6-32 
scrollable area definition 17-14 
scrolling 
area definition 17-14 
areas that can be scrolled 17-14 
data item groups 17-16 
defining 17-14 
error conditions 17-15 
function keys 17-15 
incomplete list 17-15 
information area 17-16 
list area 17-15 
menu area 17-16 
message line 17-15 
status information 17-14 
support 17-14 
text area 17-16 
SDA (screen design aid) 
compared to direct DDS source entry 2-5 
definition 1-5 
search index 
See online help information 
secondary help 
definition 18-16 
determining the sequence of records 18-18 
displaying records 18-17 
selection 
choices, Common User Access 21-53 
list where singular item can be selected, list 
displays 21-33 
selection character 
country-designated 17-13 
highlighting A-9, A-155 
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selection field 
example 6-10 
example, DDS 6-12 
horizontal 6-14 
cursor movement 6-16 
multiple-choice 
definition 6-10 
vertical 6-14 
pull-down menu 6-18 
selection indicator 6-17 
single-choice 
auto-enter 6-38 
auto-selection 6-37 
definition 6-10 
vertical 6-13 
vertical 
creating 6-13, 6-14 
cursor movement 6-15 
selection field choice 
colors and display attributes 6-40 
selection indicator 
definition 6-17 
suppressing 
in pull-down menu 6-20 
in selection field 6-17 
in selection list 6-28 
selection list 
creating 6-26 
definition 6-24 
example, DDS _ 6-26 
multiple 6-26 
selection indicator 6-28 
single 6-26 
selection list (UIM) 17-12 
self-check, System/36 application compatibility G-2 
sending 
data 3-4 
sentence-ending characters A-2 
separating with blank lines 17-36 
separator 
content A-1 
markup A-1 
Set Off (SETOF or SETOFF) keywords 
response indicators for 2-15 
SETOF or SETOFF (Set Off) keyword 
response indicators for 2-15 
SEU (source eniry utility) 
definition 1-3 
Edit display 1-3 
SFL (Subfile) keyword 4-3 
SFLCHCCTL (Subfile Choice Control) keyword 6-26 
SFLCLR (Subfile Clear) keyword 
description 4-4 
SFLCSRPRG (Subfile Cursor Progression) 
keyword 2-18 
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SFLCSRRRN (Subfile Cursor Relative Record 
Number) keyword 3-29 
SFLCTL (Subfile Control) keyword 4-3 
SFLDLT (Subfile Delete) keyword 4-4 
SFLDROP (Subfile Drop) keyword 4-4 
SFLDSP (Subfile Display) keyword 4-3 
SFLDSPCTL (Subfile Display Control) keyword 4-4 
SFLEND (Subfile End) keyword 4-4 
SFLENTER (Subfile Enter) keyword 4-4 
SFLFOLD (Subfile Fold) keyword 4-4 
SFLINZ (Subfile Initialize) keyword 4-4 
SFLLIN (Subfile Line) keyword 4-4 
SFLMLTCHC (Subfile Multiple-Choice Selection) 
keyword 6-26 
SFLMODE (Subfile Mode) keyword 3-29 
SFLMSG (Subfile Message) keyword 
description 4-4 
displaying on message line when subfile control 
record written 8-2 
messages resulting from 5-6 
SFLMSGID (Subfile Message Identifier) keyword 
description 4-4 
displaying on message line when subfile control 
record written 8-2 
example DDS source 8-5 
messages resulting from 5-6 
SFLMSGKEY (Subfile Message Key) keyword 
description 4-4 
displaying messages from program message 
queue 8-4 
SFLMSGRCD (Subfile Message Record) keyword 
description 4-4 
displaying messages from program message 
queue 8-4 
SFLNXTCHG (Subfile Next Changed) keyword 
description 4-4 
example DDS 4-22 
SFLPAG (Subfile Page) keyword 
example with ROLLUP and SFLSIZ 4-19 
use in subfile control record format 4-3 
SFLPGMQ (Subfile Program Message Queue) 
keyword 
description 4-4 
displaying messages from program message 
queue 8-4 
SFLRCDNBR (Subfile Record Number) keyword 
description 4-4 
improving subfile performance 14-1 
SFLRNA (Subfile Records Not Active) keyword 4-4 
SFLROLVAL (Subfile Roll Value) keyword 4-4 
SFLRTNSEL (Subfile Return Selected Choice) 
keyword 6-27 
SFLSCROLL (Subfile Scroll) keyword 6-28 
SFLSIZ (Subfile Size) keyword 
example with ROLLUP and SFLPAG 4-19 
use in subfile control record format 4-3 


SFLSNGCHC (Subfile Single-Choice Selection) 
keyword 6-26 
SFLMLTCHC (Subfile Multiple-Choice 
Selection) 6-26 
Subfile Multiple-Choice Selection 
(SFLMLTCHC) 6-26 
SHARE (share) parameter 
sharing display files in same job 3-50 
system performance considerations 14-2 
sharing 
open data paths 14-2 
sharing and overriding with printer file 17-37 
shift-control character 
DBCS-graphic characters D-6 
description of D-3 
inserting D-6 
sign on 
choosing sign on menu 9-3 
signed numeric data, System/36 application compat- 
ibility G-7 
simple list (SL) tag 
example, simple lists A-152 
overview A-152 
tags allowed table A-152 
use in help module 20-5 
simple menu area 
example A-112 
single selection field operation, CUA 
guidelines 21-53 
single-choice menu display 
See menu display 
single-choice selection field 
colors and display attributes 6-40 
definition 6-10 
horizontal 6-14 
in a pull-down menu 6-18 
vertical 6-13 
single-choice selection list 
creating 6-26 
definition 6-24 
example 6-25 
size 
window 5-4 
SL (simple list) tag 
example, simple lists A-152 
overview A-152 
tags allowed table A-152 
use in help module 20-5 
slash (/) symbol A-5 
SLNO (Starting Line Number) keyword 
examples 
restrictions 3-11 
table of values and results 3-11 
use 3-11 
used with other DDS keywords 3-11 
with *VAR value 3-12 


sort table 
copying DBCS master from data file D-13 
copying DBCS master to data file D-12 
source 
example confirmation panel 16-28 
example data presentation panel 16-35 
example list panel 16-17 
example menu 16-9 
example menu bar panel 16-53 
source entry utility (SEU) 
definition 1-3 
Edit display 1-3 
source file 
definition 1-2 
source member 
definition 1-2 
Specify Members to Work with display 1-2 
specifying 
enhanced display capability 6-4 
right-to-left display processing 2-19 
Start Character Generator Utility (STRCGU) 
command D-10 
Start Programming Development Manager 
(STRPDM) command 1-1 
Start Search Index (STRSCHIDX) command 20-8 
Start Source Entry Utility (SEU) display 1-3 
Start Source Entry Utility (STRSEU) command 2-7 
Starting Line Number (SLNO) keyword 
restrictions 3-11 
table of values and results 3-11 
use 3-11 
used with other DDS keywords 3-11 
with *VAR value 3-12 
STRCGU (Start Character Generator Utility) 
command D-10 
stream, user-defined data 
See user-defined data stream (UDDS) 
STRPDM (Start Programming Development 
Manager) command _ 1-1 
STRSCHIDX (Start Search Index) command 20-8 
STRSEU (Start Source Entry Utility) command 2-7 
subfile 
See also display file 
active record in, updating 4-13 
adding record at a specified location in 4-12 
checking validity of data 4-22 
controlling appearance of 4-16 
cursor, positioning 
initially 4-24 
when Fold or Truncate key used 4-27 
when more than one record displayed 4-27 
when Roll key used 4-24 
definition 2-9 
describing in DDS source 4-3 
displaying 
and processing records at the same time 4-15 
error messages from 4-23 
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subfile (continued) subfile (continued) 


displaying (continued) SFLDSP keyword, use of 4-3 
horizontally 4-16 SFLPAG keyword, use of 4-3 
horizontally with display modes 4-17 SFLSCROLL keyword, use of 6-28 
records 4-15 SFLSIZ keyword, use of 4-3 
vertically 4-16 size equal to page size 4-19 
example size not equal to page size 4-21 
*DS3 mode display 4-19 subfile control record format, purpose 4-3 
*DS4 mode display 4-18 subfile control, processing order of DDS keywords 
DDS for two display sizes 2-25 for 4-9 
DSPATR(PC) keyword, use of 4-24 subfile record format, purpose 4-3 
DSPMOD keyword, use of 4-17 table of I/O requests in high-level languages 
message subfile 4-23 BASIC statements 4-15 
program logic for subfiles 4-31 ILE C functions 4-15 
ROLLUP, SFLSIZ, and SFLPAG keywords 4-19 ILE COBOL statements 4-15 
sample display for changing information 4-2 ILE RPG operations 4-15 
sample display for display only 4-1 USRDSPMGT keyword restriction G-10 
sample display for input only 4-2 validity checking before rolling 4-9 
sample display for task combination 4-2 window 5-6 
sample display with selection 4-1 Subfile Choice Control (SFLCHCCTL) keyword 6-26 
sample displays when rolling two or more Subfile Clear (SFLCLR) keyword 
records 4-28 description 4-4 
SFLNXTCHG keyword, use of 4-22 Subfile Control (SFLCTL) keyword 4-3 
SFLPAG, SFLSIZ, and ROLLUP keywords 4-19 subfile control record format 
SFLSIZ, ROLLUP, and SFLPAG keywords 4-19 definition 4-3 
variable-length record 4-20 placement after subfile record format 4-4 
vertical and horizontal, displayed at same read operation 4-15 
time 4-16 requesting I/O operations for 4-15 
extending full 4-9 required DDS keywords 4-3 
functions for 4-4 SFLCTL keyword, use of 4-3 
high-level language programs, use in 4-10 SFLDSP keyword, use of 4-3 
maximum number active to display station 4-9 SFLPAG keyword, use of 4-3 
maximum number allowed in display file 4-9 SFLSIZ keyword, use of 4-3 
multiple records 4-1 write operation 4-15 
optional functions, table of 4-4 write-read operation 4-15 
order of subfile record format and subfile control Subfile Cursor Progression (SFLCSRPRG) 
record format 4-4 keyword 2-18 
performance considerations 14-1 Subfile Cursor Relative Record Number 
placing records on display for processing 4-15 (SFLSCRRRN) keyword 3-29 
positioning cursor for each page of records 4-24 Subfile Delete (SFLDLT) keyword 4-4 
program logic for 4-31 Subfile Display (SFLDSP) keyword 4-3 
reading active record at specified location in 4-13 Subfile Display Control (SFLDSPCTL) keyword 4-4 
reading next changed record in 4-14 Subfile Drop (SFLDROP) keyword 4-4 
recognizing uses of Subfile End (SFLEND) keyword 4-4 
changing information 4-2 Subfile Enter (SFLENTER) keyword 4-4 
combination of tasks 4-2 Subfile Fold (SFLFOLD) keyword 4-4 
display only 4-1 Subfile Initialize (SFLINZ) keyword 4-4 
input only without validity checking 4-2 Subfile Line (SFLLIN) keyword 4-4 
sample display with selection 4-1 Subfile Message (SFLMSG) keyword 
records description 4-4 
active subfile 4-4 displaying on message line when subfile control 
inactive subfile 4-4 record written 8-2 
requesting I/O operations for 4-12 messages resulting from 5-6 
rolling and validity checking 4-9 Subfile Message Identifier (SFLMSGID) keyword 
SFL keyword, use of 4-3 defining in display 8-4 
SFLCTL keyword, use of 4-3 description 4-4 
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Subfile Message Identifier (SFLMSGID) keyword 
(continued) 
displaying on message line when subfile control 
record written 8-2 
messages resulting from 5-6 
Subfile Message Key (SFLMSGKEY) keyword 
description 4-4 
displaying messages from program message 
queue 8-4 
Subfile Message Record (SFLMSGRCD) keyword 
description 4-4 
displaying messages from program message 
queue 8-4 
Subfile Mode (SFLMODE) keyword 3-29 
Subfile Multiple-Choice Selection (SFLMLTCHC) 
keyword 6-26 
Subfile Next Changed (SFLNXTCHG) keyword 
description 4-4 
example DDS 4-22 
Subfile Page (SFLPAG) keyword 
example with ROLLUP and SFLSIZ 4-19 
use in subfile control record format 4-3 
Subfile Program Message Queue (SFLPGMQ) 
keyword 
description 4-4 
displaying messages from program message 
queue 8-4 
subfile record format 
definition 4-3 
get-next-changed operation 4-14 
get-relative operation 4-13 
placement before subfile control record format 4-4 
put-relative operation 4-12 
requesting I/O operations for 4-12 
SFL keyword, use of 4-3 
update operation 4-13 
Subfile Record Number (SFLRCDNBR) keyword 
description 4-4 
Subfile Records not Active (SFLRNA) keyword 4-4 
Subfile Return Selected Choice (SFLRTNSEL) 
keyword 6-27 
Subfile Roll Value (SFLROLVAL) keyword 4-4 
Subfile Scroll (SFLSCROLL) keyword 6-28 
Subfile Single-Choice Selection (SFLSNGCHC) 
keyword 6-26 
Subfile Size (SFLSIZ) keyword 
example with ROLLUP and SFLPAG 4-19 
use in subfile control record format 4-3 
suppressed selection indicator in pull-down menu 
example 6-21 
suppressed selection indicator in selection field 
example 6-18 
symbol 
ampersand (&) A-5 
colon (:) A-5 
concatenation A-5 


symbol (continued) 

message text 

message file default A-5 

period (.) A-5 

right slash (/) A-5 
symmetric character 

Arabic A-23 

Hebrew A-23 
synonym, index search 

See online help information 


System Command (CMD) dialog command 


system menu 9-1 
system message 
See message 
system performance 
See performance 
system value 
QIGC for DBCS conversion dictionaries 
creating D-15 
deleting D-19 
display D-19 
edit, examples of D-17 
editing (adding and changing terms) 


D-16 


B-7 


perform object management functions with D-15 


printing D-19 

System/36 application compatibility 
ASSUME (Assume) keyword G-2 
cancel-invite operation G-8 
display files G-1 
ERASE (Erase) keyword G-2 
function keys G-7 
HELP (Help) keyword G-7 
Help Return (HLPRTN) keyword G-7 
high-level languages G-1 
HLPRTN (Help Return) keyword G-7 
input data G-2 
KEEP (Keep) keyword G-2 
messages G-4 
OVERLAY keyword G-2 


PUTOVR (Put with Explicit Override) keyword G-6 
PUTRETAIN (Put-Retain) keyword G-2 


T 


tab key 
movement 6-61 
tag 
definition A-1 


MENUGRP (menu group) A-114 
tag language 
See panel group definition language 
tag within help module 
CIT (title citation) 
use in help module 20-4 
definition list (DL) 
use in help module 20-5 


Index 
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tag within help module (continued) 


DL (definition list) 

use in help module 20-5 
example (XMP) 

use in help module 20-6 
extended help headings (XH1-XH4) 

use in help module 20-4 
FIG (figure) 

use in help module 20-6 
figure (FIG) 

use in help module 20-6 
H1 through H4 (headings) 

use in help module 20-4 
heading (H1 through H4) 

use in help module 20-4 
HELP (help module) 

panel groups with help modules 20-2 

placement in UIM source 20-2 
help module (HELP) 

panel groups with help modules 20-2 

placement in UIM source 20-2 
highlighted phrase (HPO-HP9) 

use in help module 20-4 
HPO-HP9 (highlighted phrase) 

use in help module 20-4 
hypertext link (LINK) 

placement in UIM source 20-15 
imbed help (IMHELP) 

placement in panel group source 20-2 
IMHELP (imbed help) 

panel groups using 20-2 

placement in panel group source 20-2 
IMPORT (import) 

panel groups using 20-3 

placement in UIM source 20-3 
index search (ISCH) 

placement in UIM source 20-9 
index search synonym (ISCHSYN) 

placement in UIM source 20-9 
ISCH (index search) 

panel groups using 20-9 

placement in UIM source 20-9 
ISCHSYN (index search synonym) 

panel groups using 20-9 

placement in UIM source 20-9 
LINES (unformatted lines) 

use in help module 20-6 
LINK (hypertext link) 

panel groups using 20-15 

placement in UIM source 20-15 
list part (LP) 

use in help module 20-5 
LP (list part) 


tag within help module (continued) 


note (NT) 

use in help module 20-4 
NT (note) 
OL (ordered list) 

use in help module 20-5 
ordered list (OL) 

use in help module 20-5 
P (paragraph) 

placement in UIM source 20-2 

use in help module 20-4 
panel group (PNLGRP) 

placement in UIM source 20-2 
panel markup 

definition 20-4 
paragraph (P) 

use in help module 20-4 
paragraph continuation (PC) 

use in help module 20-4 
parameter list (PARML) 

use in help module 20-5 
PARML (parameter list) 

use in help module 20-5 
PC (paragraph continuation) 

use in help module 20-4 
PK (programming keyword) 

use in help module 20-5 
PNLGRP (panel group) 

panel groups with help modules 20-2 

placement in UIM source 20-2 
programming keyword (PK) 

use in help module 20-5 
programming variable (PV) 

use in help module 20-5 
purpose 20-1 
PV (programming variable) 

use in help module 20-5 
simple list (SL) 

use in help module 20-5 
SL (simple list) 

use in help module 20-5 
title citation (CIT) 

use in help module 20-4 
UL (unordered list) 

use in help module 20-5 
unformatted lines (LINES) 

use in help module 20-6 
unordered list (UL) 

use in help module 20-5 
XH1 through XH4 (extended help heading) 

use in help module 20-4 
XMP (example) 

use in help module 20-6 


use in help module 20-5 tag, modified data 2-10 
NOTE (note) tag, UIM 
use in help module 20-4 APPFMT (application formatted area) A-8 
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tag, UIM (continued) 
BOTINST (bottom instruction) A-10 
CHECK (validity checking) A-11 
CIT (title citation) A-13 
CLASS (class definition) A-14 
CMDLINE (command line) A-26 
COND (condition definition) A-27 
COPYR (copyright) A-30 
DATA (data presentation area) A-31 
DATAC (data item choices) A-38 
DATACOL (data column) A-39 
DATAGRP (data group) A-40 
DATAI (data item) A-42 
DATAIX (data item extender) A-47 
DATASLT (data selection field) A-51 
DATASLTC (data selection field choice) A-55 
DL (definition list) A-57 
FIG (figure) A-59 
H1 through H4 (heading) A-65 
HELP (help module) A-60 
HPO through HP9 (highlighted phrase) A-63 
IMHELP (imbed help) A-66 
IMPORT (import) A-67 
INFO (information area) A-68 
ISCH (index search) A-70 
ISCHSUBT (index search subtopic) A-71 
ISCHSYN (index search synonym) A-72 
KEYI (key list item) A-74 
KEYL (key list) A-76 
LINES (unformatted lines) A-77 
LINK (hypertext link definition) A-78 
LIST (list area) A-82 
LISTACT (list action) A-90 
LISTCOL (list column) A-96 
LISTDEF (list definition) A-100 
LISTGRP (list column group) A-103 
LISTVIEW (list view) A-105 
LP (list part) A-107 
MBAR (menu bar) A-108 
MBARC (menu bar choice) A-110 
MENU (menu area) A-111 
MENUI or MI (menu item) A-115 
NT or NOTE (note) A-117 
OL (ordered list) A-118 
OPTLINE (option line) A-120 
P (paragraph) A-121 
PANEL (display panel) A-122 
PARML (parameter list) A-129 
PC (paragraph continuation) A-131 
PDACCEL (pull-down accelerator) A-132 
PDFLD (pull-down field) A-133 
PDFLDC (pull-down field choice) A-134 
PK (programming keyword) A-138 
PNLGRP (panel group) A-139 
PRTHEAD (print head panel) A-142 
PRTPNL (print panel) A-146 


tag, UIM (continued) 
PRTTRAIL (print trailer message) A-148 
PV (programming variable) A-149 
RT (reverse text) A-150 
SL (simple list) A-152 
TEXT (text area) A-154 
TI (translation list item) A-158 
TL (translation list) A-159 
TOPINST (top instruction) A-161 
TT (truth table) A-162 
TTROW (truth table row) A-163 
UL (unordered list) A-164 
VAR (variable definition) A-166 
VARRCD (variable record definition) A-169 
XH1 through XH4 (extended help headings) A-170 
XMP (example) A-171 
tape device file 
DBCS D-5 
text (TEXT area) tag 
overview A-154 
text area 
scrolling 17-16 
text area (TEXT) tag 
example 
a text area A-157 
text data A-155 
text area scrolling 17-16 
text area, descriptive 
entry displays 21-16 
text data 
selection characters A-155 
TI (translation list item) tag 
overview A-158 
time value 
display form A-25 
timing function on WAITRCD parameter 3-33 
tips 
Word Wrap (WRDWRAP) keyword 2-21 
title 
entry displays 21-11 
information displays 21-19 
list display 21-22 
single-choice menu displays 21-9 
window 5-9 
title citation (CIT) tag 
example 
title citations A-13 
overview A-13 
use in help module 20-4 
title lines 
table A-144 
TL (translation list) tag 
list, translation A-159 
overview A-159 
tags allowed table A-159 
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tool, command line 21-37 
top instruction (TOPINST) tag 
overview A-161 
topics, index search 
See online help information 
TOPINST (top instruction) tag 
overview A-161 
trailer message 
example A-148 
trailer printing 17-36 
translation 
character set and code page, UIM A-19 
translation list (TL) tag 
list, translation A-159 


UDDS (user-defined data streams) (continued) 


output record area for record format 10-2 
system operations to request commands’ 10-4 
understanding limitations 10-2 
using 10-1 
USRDFN (User-Defined) keyword 10-1 
valid keywords with USRDFN keyword 10-2 
write-read function 10-4 
write-read operations 

CL (control language) 10-4 

ILE COBOL 10-4 

ILE RPG 10-4 


UIM 


commonly asked questions 17-37 


overview A-159 UIM (user interface manager) 
tags allowed table A-159 See also panel group 
translation list item (TI) tag 5250 engraved key restrictions 17-14 
overview A-158 action list definition 17-11 
translation table 13-4 action variable definition 17-11, 17-13 
truth table (TT) tag adding pop-up window over another panel 17-27 
example, truth table A-162 adding window over another panel 17-27 
overview A-162 after scrolling example 16-33 
tags allowed table A-162 alternate view of list example 16-15 
truth table row (TTROW) tag APl services 16-5 
overview A-163 application handle definition 17-1 
TT (truth table) tag application programming 
example, truth table A-162 confirmation processing 16-31 


overview A-162 data presentation panel 16-46 
tags allowed table A-162 list panel 16-25 
TTROW (truth table row) tag menu bar panel 16-63 
overview A-163 application window, defining 17-30 
two presentation areas for data items automatic confirmation processing 16-31 
example A-35 command line 
two-column format in a data entry panel entered too long 17-20 
example A-34 interpretation 17-19 
type pop-up window 17-32 
display station 5-3, 6-1 restrictions 17-19 
window 17-32 
U window example 17-32 
confirmation list panel, creating 16-27 


UDDS (user-defined data streams) 
3270 Model 4 display station support 10-3 confirmation processing 
available functions 10-2 application programming 16-31 
buffer format for 5250 display station 10-3 automatically 16-31 
command attention keys, effects on 10-3 considerations before using 15-1 
command function keys, effects on 10-3 contextual help, defining 17-16 
defining output buffer 10-3 controlling list entries on list display 17-10 
defining output data stream 10-3 conversion of character set and code page A-19 


confirmation panel source 16-28 


display station differences, understanding 10-1 creating 

handling of field-level requests after user-defined confirmation list panel 16-27 
requests 10-2 data presentation panel 16-32 

help information for 10-2 list panel 16-13 

I/O requests, effect on 10-2 menu bar panel 16-50 

input operations 10-4 menu panel 16-6 

limitations 10-2 object 16-3 


opening display files containing 10-3 cursor position when help text displayed 17-17 
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UIM (user interface manager) (continued) 


data entry panel 16-49 
data presentation panel 
application programming 16-46 
creating 16-32 
example 16-32 
source 16-35 


DBCS and national language considerations 20-12 


DDS instead of 15-1 
defining 
application window 17-30 
contextual help 17-16 
dialog variable 17-1 
function keys 17-20 
function keys and VARUPD value 17-21 
menu object 16-6 
panel group object 16-13 
definition 1-1 
details 17-1 
dialog variable 
definition 17-1 
error messages 17-3 
incorrect characters 17-4 
initial value 17-2 
restrictions 17-3 


differences between pull-down menus and pop-up 


windows 17-28 
display characters, incorrect 17-4 
display panel field value using dialog variables 
displaying list 17-8 
displaying panel using request processor 
program 17-33 
elements within panel group 16-3 
entry pointer for list 17-10 
error messages for dialog variables 17-3 
example 
alternate view of list 16-15 
list panel 16-14 
menu bar panel 16-50 
menu source 16-9 
exit flag 17-24 
field value for display panel using dialog 
variables 17-4 
folding up list panel 17-26 
folding up multiple panels when EXIT 
requested 17-24 
folding when EXIT requested 17-24 
formatting function keys 17-20 
function key 
defining 17-20 
formatting 17-20 
scrolling 17-15 
VARUPD value 17-21 
functions supported 16-2 
graphical user interface (GUI) 17-14 
help 
hierarchy, index search 20-11 


UIM (user interface manager) (continued) 


help (continued) 

index search 19-4 

index search hierarchy 20-11 

InfoSeeker 19-3 

user-defined panel group 19-4 
help text displayed according to cursor 

position 17-17 

help window 5-9 
incorrect characters in dialog variable 17-4 
incorrect display characters 17-4 
incorrect printer characters 17-4 
increasing user productivity 15-1 
index search 

giving help panels access 19-4 
InfoSeeker 19-3 
initial value of dialog variable 17-2 
initializing list 17-8 
inserting entry from list 17-10 


interactive response time for list displays 17-11 


introduction 16-1 
limitations of panel formatter 17-24 
list 
displaying 17-8 
incomplete processing 17-9 
initialing 17-8 
inserting entry from 17-10 
managing 17-7 
removing entry from 17-10 
updating 17-9 
list display 
controlling list entries 17-10 
list entry 
handle 17-9 
on list display 17-10 
pointer 17-10 
list panel 
application programming 16-25 
creating 16-13 
example 16-14 
fold up 17-26 
source 16-17 
managing panel functions 17-13 
menu area, scrolling 17-16 
menu bar panel 
application programming 16-63 
creating 16-50 
example 16-50 
source 16-53 
menu bars 17-27 
menu definition 16-2 
menu object 16-6 
menu panel 
creating 16-6 
example 16-6 
message line, scrolling 17-15 


Index 
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UIM (user interface manager) (continued) 


national language considerations and DBCS 20-12 


opening application 17-1 
panel elements supported 16-2 
panel formatter limitations 17-24 
panel formatting 
application control 17-23 
concepts 17-22 
definition 17-22 
when to perform 17-22 
panel function managing 17-13 
panel group 
definition 16-2 
elements 16-3 
panel group object, defining 16-13 
panel list fold up 17-26 
pop-up window 
adding 17-30, 17-31 
adding and removing using APIs_ 17-30 
adding over another panel 17-27 
adding to display stack 17-30, 17-31 
API for adding and removing 17-30 
command line 17-32 
defining application 17-30 
example in command line 17-32 
removing 17-31 
removing using APIs 17-30 
using 17-30 
pop-up window and pull-down menu 
differences 17-28 
printer characters, incorrect 17-4 
printing 17-33 
blank lines for separating 17-36 
character set and code page 17-5 
code page and character set 17-5 
concepts 17-33 
DBCS (double-byte character set) 17-37 
double-byte character set (DBCS) 17-37 
fonts and highlighting 17-36 
header area 17-36 
highlighting 17-36 
highlighting and fonts 17-36 
introduction 17-33 


overriding with and sharing printer file 17-37 


page eject 17-37 
print head panel 17-35 
print panel 17-35 


printer file, sharing and overriding with 17-37 


prolog area 17-36 
separating with blank lines 17-36 


sharing and overriding with printer file 17-37 


trailer 17-36 
productivity 
improvements 15-1 
increasing application programmer 15-1 
pull-down menu and pop-up window 
differences 17-28 
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UIM (user interface manager) (continued) 
removing entry from list 17-10 
request processor program when displaying 
panel 17-33 
response time for list displays 17-11 
restrictions 
5250 engraved keys 17-14 
using dialog variables 17-3 
routing step 17-13 
scrolling 
area definition 17-14 
areas that can be scrolled 17-14 
data item groups 17-16 
defining scrollable areas 17-14 
error conditions 17-15 
function key 17-15 
incomplete list 17-15 
information area 17-16 
list area 17-15 
menu area 17-16 
message line 17-15 
status information 17-14 
text area 17-16 
selection characters 17-13 
selection list definition 17-12 
source 
example confirmation panel 16-28 
example data presentation panel 16-35 
example list panel 16-17 
example menu 16-9 
example menu bar panel 16-53 
updating list 17-9 
user-defined panel group 
giving help panels access 19-4 
using DDS instead of 15-1 
variable pool services 17-4 
VARUPD value and function keys 17-21 
when to use to gain productivity 15-1 
window 
adding 17-30, 17-31 
adding and removing using APIs_ 17-30 
adding over another panel 17-27 
adding to display stack 17-30, 17-31 
API for adding and removing 17-30 
command line 17-32 
defining application 17-30 
example in command line 17-32 
removing 17-31 
removing using APIs_ 17-30 
using 17-30 
UIM-defined variable attributes A-167 
UL (unordered list) tag 
example, unordered list A-165 
overview A-164 
tags allowed table A-164 
use in help module 20-5 


unavailable choice 
example 6-37 
unformatted lines (LINES) tag 
example, unformatted lines A-77 
overview A-77 
use in help module 20-6 
UNLOCK (Unlock Keyboard) keyword 
effects on input operation 3-36 
example with INZRCD keyword 3-36 
unlocking keyboard while the program is processing 
data 3-35 
unordered list (UL) tag 
example, unordered list A-165 
overview A-164 
tags allowed table A-164 
use in help module 20-5 
update operation for subfiles 
BASIC statement for 4-15 
definition 4-13 
ILE C function for 4-15 
ILE COBOL statement for 4-15 
ILE RPG operation for 4-15 
updating 
list in UIM 17-9 
updating pull-down menu 6-55 
User Defined (USRDFN) keyword 
See user-defined data stream (UDDS) 
User Display Management (USRDSPMGT) keyword 
DDS keywords that cannot be used with G-2 
use G-1 
user interface manager (UIM) 
See also panel group 
5250 engraved key restrictions 17-14 
action list definition 17-11 
action variable definition 17-11, 17-13 
adding pop-up window over another panel 17-27 
adding window over another panel 17-27 
alternate view of list example 16-15 
APl services 16-5 
application handle definition 17-1 
application programming 
confirmation processing 16-31 
data presentation panel 16-46 
list panel 16-25 
menu bar panel 16-63 
application window, defining 17-30 
automatic confirmation processing 16-31 
command line 
entered too long 17-20 
interpretation 17-19 
pop-up window 17-32 
restrictions 17-19 
window 17-32 
window example 17-32 
commonly asked questions 17-37 
confirmation list panel, creating 16-27 


user interface manager (UIM) (continued) 


confirmation panel source 16-28 
confirmation processing 
application programming 16-31 
automatically 16-31 
considerations before using 15-1 
contextual help, defining 17-16 
controlling list entries on list display 17-10 
conversion of character set and code page A-19 
creating 
confirmation list panel 16-27 
data presentation panel 16-32 
list panel 16-13 
menu bar panel 16-50 
menu panel 16-6 
object 16-3 
cursor position when help text displayed 17-17 
data entry panel 16-49 
data presentation panel 
after scrolling example 16-33 
creating 16-32 
example 16-32 
source 16-35 
DBCS and national language considerations 20-12 
DDS instead of 15-1 
defining 
application window 17-30 
contextual help 17-16 
dialog variable 17-1 
function keys 17-20 
function keys and VARUPD value 17-21 
menu object 16-6 
panel group object 16-13 
defining menu object 16-6 
defining panel group object 16-13 
definition 1-1 
details 17-1 
dialog variable 
definition 17-1 
error messages 17-3 
incorrect characters 17-4 
initial value 17-2 
restrictions 17-3 
differences between pull-down menus and pop-up 
windows 17-28 
display characters, incorrect 17-4 
display panel field value using dialog variables 17-4 
displaying list 17-8 
displaying panel using request processor 
program 17-33 
elements within panel group 16-3 
enabling graphical user interface (GUI) 17-14 
entry pointer for list 17-10 
error messages for dialog variables 17-3 
example 
alternate view of list 16-15 
list panel 16-14 
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user interface manager (UIM) (continued) 


example (continued) 
menu bar panel 16-49 
menu source 16-9 
exit flag 17-24 
field value for display panel using dialog 
variables 17-4 
folding up list panel 17-26 
folding up multiple panels when EXIT 
requested 17-24 
folding when EXIT requested 17-24 
formatting function keys 17-20 
function key 
defining 17-20 
formatting 17-20 
scrolling 17-15 
VARUPD value 17-21 
functions supported 16-2 
graphical user interface (GUI) 17-14 
help 
hierarchy, index search 20-11 
index search 19-4 
index search hierarchy 20-11 
user-defined panel group 19-4 
help text displayed according to cursor 
position 17-17 
help window 5-9 
incorrect characters in dialog variable 17-4 
incorrect display characters 17-4 
incorrect printer characters 17-4 
increasing user productivity 15-1 
index search 
giving help panels access 19-4 
InfoSeeker 19-3 
initial value of dialog variable 17-2 
initializing list 17-8 
inserting entry from list 17-10 
interactive response time for list displays 17-11 
introduction 16-1 
limitations of panel formatter 17-24 
list 
defining 17-8 
displaying 17-8 
incomplete processing 17-9 
initialing 17-8 
inserting entry from 17-10 
managing 17-7, 17-8 
removing entry from 17-10 
updating 17-9 
list display 
controlling list entries 17-10 
list entry 
handle 17-9 
on list display 17-10 
pointer 17-10 
list panel 
application programming 16-25 


X-58 Application Display Programming V4R1 


user interface manager (UIM) (continued) 
list panel (continued) 
creating 16-13 
example 16-14 
fold up 17-26 
source 16-17 
managing panel functions 17-13 
menu area, scrolling 17-16 
menu bar 17-27 
menu bar panel 16-50 
application programming 16-63 
creating 16-50 
example 16-49 
source 16-53 
menu definition 16-2 
menu object, defining 16-6 
menu panel 
creating 16-6 
example 16-6 
message line, scrolling 17-15 


national language considerations and DBCS 20-12 


opening application 17-1 
panel elements supported 16-2 
panel formatter limitations 17-24 
panel formatting 
application control 17-23 
concepts 17-22 
definition 17-22 
when to perform 17-22 
panel function managing 17-13 
panel group 
definition 16-2 
elements 16-3 
panel group object, defining 16-13 
panel list fold up 17-26 
pop-up window 
adding 17-30, 17-31 
adding and removing using APIs_ 17-30 
adding over another panel 17-27 
adding to display stack 17-30, 17-31 
API for adding and removing 17-30 
command line 17-32 
defining application 17-30 
example in command line 17-32 
removing 17-31 
removing using APIs_ 17-30 
using 17-30 
pop-up window and pull-down menu 
differences 17-28 
printer characters, incorrect 17-4 
printing 17-33 
blank lines for separating 17-36 
character set and code page _ 17-5 
code page and character set 17-5 
concepts 17-33 
DBCS (double-byte character set) 17-37 
double-byte character set (DBCS) 17-37 


user interface manager (UIM) (continued) user interface manager (UIM) (continued) 


printing (continued) when to use to gain productivity 15-1 
fonts and highlighting 17-36 window 
header area 17-36 adding 17-30, 17-31 
highlighting and fonts 17-36 adding and removing using APIs_ 17-30 
introduction 17-33 adding over another panel 17-27 
overriding with and sharing printer files 17-37 adding to display stack 17-30, 17-31 
page eject 17-37 API for adding and removing 17-30 
print head panel 17-35 command line 17-32 
print panel 17-35 defining application 17-30 
printer file, sharing and overriding with 17-37 example in command line 17-32 
prolog area 17-36 removing 17-31 
separating with blank lines 17-36 removing using APIs_ 17-30 
sharing and overriding with printer files 17-37 using 17-30 
trailer 17-36 User Restore Display (USRRSTDSP) keyword 5-13 
productivity user-created dictionary (QUSRIGCDCT) D-15 
improvements 15-1 user-defined data streams (UDDS) 
increasing application programmer 15-1 3270 Model 4 display station support 10-3 
pull-down menu and pop-up window available functions 10-2 
differences 17-28 buffer format for 5250 display station 10-3 
removing entry from list 17-10 command attention keys, effects on 10-3 
request processor program when displaying command function keys, effects on 10-3 
panel 17-33 defining output buffer 10-3 
response time for list displays 17-11 defining output data stream 10-3 
restrictions display station differences, understanding 10-1 
5250 engraved keys 17-14 handling of field-level requests after user-defined 
using dialog variables 17-3 requests 10-2 
routing step 17-13 help information for 10-2 
scrolling I/O requests, effect on 10-2 
area definition 17-14 input operations 10-4 
areas that can be scrolled 17-14 limitations 10-2 
data item group 17-16 opening display files containing 10-3 
defining scrollable areas 17-14 output record area for record format 10-2 
error conditions 17-15 system operations to request commands 10-4 
function key 17-15 understanding limitations 10-2 
incomplete list 17-15 using 10-1 
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DSMMOM395I '.EDFPO' LINE 70: ._po @E@P@S 

DSMMOM397I '!EDFPO' WAS IMBEDDED AT LINE 70 OF 'EDFPO' 

DSMMOM397I '!EDFPO' WAS IMBEDDED AT LINE 910 OF '.EDFAWRK' 

DSMMOM397I 'EDFAWRK' WAS IMBEDDED AT LINE 3433 OF 'RBAHGAPD' 

DSMMOM397I 'RBAHGAPD' WAS IMBEDDED AT LINE 87 OF 'RBAHGMST' 

DSMKPO660W POSTSCRIPT FILE'S LINE LENGTH VIOLATES ADOBE STRUCTURING CONVE 
NTIONS. 

DSMMOM395I '.EDFPO' LINE 70: ._po @E@P@S 

DSMMOM397I '!EDFPO' WAS IMBEDDED AT LINE 70 OF 'EDFPO' 

DSMMOM397I '!EDFPO' WAS IMBEDDED AT LINE 910 OF '.EDFAWRK' 

DSMMOM397I '!EDFAWRK' WAS IMBEDDED AT LINE 3448 OF 'RBAHGAPD' 

DSMMOM397I 'RBAHGAPD' WAS IMBEDDED AT LINE 87 OF 'RBAHGMST' 

DSMKPO660W POSTSCRIPT FILE'S LINE LENGTH VIOLATES ADOBE STRUCTURING CONVE 
NTIONS. 

DSMMOM395I '.EDFPO' LINE 70: ._po @E@P@S 

DSMMOM397I '-EDFPO' WAS IMBEDDED AT LINE 70 OF 'EDFPO' 

DSMMOM397I '-EDFPO' WAS IMBEDDED AT LINE 910 OF '".EDFAWRK' 

DSMMOM397I 'EDFAWRK' WAS IMBEDDED AT LINE 3463 OF 'RBAHGAPD' 

DSMMOM397I 'RBAHGAPD' WAS IMBEDDED AT LINE 87 OF 'RBAHGMST' 

DSMKPO660W POSTSCRIPT FILE'S LINE LENGTH VIOLATES ADOBE STRUCTURING CONVE 
NTIONS. 

DSMMOM395I '.EDFPO' LINE 70: ._po @E@P@S 

DSMMOM397I '!EDFPO' WAS IMBEDDED AT LINE 70 OF 'EDFPO' 

DSMMOM397I '.EDFPO' WAS IMBEDDED AT LINE 910 OF '".EDFAWRK' 

DSMMOM397I "EDFAWRK' WAS IMBEDDED AT LINE 3471 OF 'RBAHGAPD' 

DSMMOM397I 'RBAHGAPD' WAS IMBEDDED AT LINE 87 OF 'RBAHGMST' 


